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demos of Windows applications. 

DemoShield4 gives you the power to 
effortlessly create convincing point-and- 
click product demos, presentations and 
tutorials of your 


The Power 


application. 

Simply use a 
sample demo 
or customize 
your own 
interactive 
demo with 
special 
effects—all 
without programming. DemoShield4 
gives your customers a chance to interact 
with your application in real time while 
experiencing key product features. 

Let DemoShield4 do the selling for you. 
After all, it's a dog eat dog world out 
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From the Editor 



hen you need a disassem¬ 
bler you're looking for clear, reliable informa¬ 
tion. Those who have tried other products 
have been disappointed with the dismal re¬ 
sults. 

Clearly, a new standard of excellence! 

Sourcer solves these problems with ad¬ 
vanced analysis and simulation. The quality 
of output is so good that most DOS EXE & 
COM files and drivers reassemble perfectly, 
byte-for-byte identical to the original! 

To make the results easier to understand 
Sourcer provides detailed and descriptive 
comments for interrupt subfunctions, I/O 
ports and much more. Sourcer even lets you 
examine encrypted and packed programs. 


mov 

ax,2517h 


mov 

dx.offset int 17h entry 

int 

21 h 

; DOS Services ah=function 25h 
; set intrpt vector al to ds:dx 
; ('Halt when ? printed.') 

mov 

dx.offset data 4 

mov 



int 

21 h 

: DOS Services ah=function 09h 
; display char string at ds:dx 

mov 

dx.l9h 


mov 

ah,31h 



; DOS Services ah=function 31 h 



; terminate and stay resident 
; al=retum code,dx=paragraphs 

virustst endp 




int_17h_entry proc 
pushf 

far 

Push flags 

emp 

al,3Fh 
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fying the use of parameter passing and local 
stack variables. Parameters pushed onto the 
stack prior to a subroutine call are clearly com¬ 
mented. 

Get commented BIOS listings 

The BIOS Pre-Processor creates commented 
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Windows disassembly! 
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of Windows EXEs, DLLs, VxDs, device 
drivers, & OS/2 NE files. Windows Source 
labels, by name, export & import function calls, 
API calls like "GetModuleHandle”, undocu¬ 
mented APIs, VxD functions and much more. 
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Sourcer & BIOS Pre-processor 189.95 
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Shipping: USA $6: Canada/Mexico $10; Ail others $25. 

CA residents add sales tax. © 1994 VISA/MC/Amex/COD 

30-DAY MONEY-BACK GUARANTEE 
V Communications, Inc. 
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San Jose, CA 95129 408-296-4224 
FAX 408-296-4441 
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I finally broke down and bought a copy of Visual C++ v4.0. One reason I've been in no hurry to plop 
down my $$ for the upgrade is that I still have to maintain 16-bit Windows code, and Microsoft stopped 
updating the 16-bit half of Visual C++ years ago, so it just keeps getting more broken as time goes by. 
For example, I haven't been able to get the 16-bit CodeView for Windows to work under Windows 95. 
As another example, the 16-bit VC++ ships with a wi ndowsx. h that is too out-of-date to include 16/32-bit 
portability macros like GET_WM_VSCROLL_POS(). If you need to maintain 16-bit Windows code or do dual 
16/32-bit development, better get Borland C++ v5.0. AT Want to see some renegade programmers take 
on the MS megalomonolith? Check out http://www.envelop.com, where you'll find a free copy of the 
Envelop Engine, a tool designed to compete with Visual Basic. It's not a trivial tool, and they're giving it 
away free in hopes of making their money back by supporting the creation and sale of components. 
They're looking for developers to join their Enveloper Corps and help build components for their engine. 
AT Although we've stopped giving out free T-shirts for SDK Annotations, we've got plenty left to give 
out for new Windows bugs. Did you pass a new Win32 function some legal data and watch it bring down 
the system? We want to hear about. Send your candidate for Windows Bug of the Month to 
70302.2566@compuserve. com, and if we use your bug, we'll give you the shirt off our back (or a new one, 
if you insist). AT Microsoft usually isn't at the cutting edge of either software development or human 
resource management, but they definitely do a couple of smart things many companies don't. For one 
thing, they have a good technical library, with staff that can respond to email requests for information 
and provide literature searches. For another, they provide free magazine subscriptions for their pro¬ 
grammers — it's as easy as filling out an email form. AT I've managed to somehow only recently grasp 
the fact that Win95 does not support asynchronous disk I/O. This means that all the dilettante technical 
columnists telling people to make use of threads in their programs (as though threads are good for every¬ 
thing) are even more wrong-headed than I thought. The most likely way the average program could 
benefit from multi-threading is by doing useful work while waiting for disk I/O to complete. But that 
simply does not work under Windows 95. Once again, NT got it right — it handles asynchronous disk 
I/O with no problem. Not to mention the fact that thread context switches are almost three times faster 
under NT than under Windows 95. AT Attention book publishers: we're revising our procedure for 
Books in Brief. In the past, we asked books be sent to Lawrence, where the main office is. That sometimes 
caused headaches, since three magazines are, published there and all books were placed in a common 
pool available to all the editors. Though you can still send books to the Lawrence office, you can now 
send books directly to me; each book I receive that is clearly relevant to Windows programmers will be 
listed in the "Books Received" section of Books in Brief, and will be considered for review. My shipping 
address is now listed with each installment of the column. AT Attention book authors: Ever wonder 
why your Windows-related programming book didn't get mentioned in Books in Brief? Most likely, we 
never received a copy of it. Most publishers do not regularly send us review copies, and often they don't 
manage to ship us a copy even when the author specifically requests it. If you want to be on the safe side, 
you may want to ship us a review copy yourself. AT I was talking with someone about their cowork¬ 
er, a former UNIX programmer who keeps struggling to make their NT environment look like UNIX. We 
agreed that the best course is usually to just bite the bullet and convert to using whatever new operating 
system you're stuck with; trying to make it act in ways it was not designed for can waste more time than 
just making the best of a different (even inferior) toolset. But then I realized, I'm that guy — I've man¬ 
aged to never really adapt to Windows (e.g., I use DOS shells and can't use File Manager to save my life). 
I vowed to embrace the Win95 GUI, or at least learn all I can about how to make it work for me. AT 
The problem with that vow is one I run into a lot — Microsoft makes lousy documentation, even for end 
users. Fortunately, the solution was only $39.99, and came in the form of Windows 95 Secrets, by Brian 
Livingston and Davis Straub. This book is pretty good for the programmer who wants to quickly get up 
to speed on the Win95 GUI. Within 30 minutes, I finally grasped how shortcuts work and how to use 
them to intelligently organize my desktop so it can contain groups of related tasks. AT I was prema¬ 
ture in handing out kudos to Microsoft for documenting how to add your own objects to the shell's 
namespace — they so far have failed to deliver. AT How about a free VBX for writing client or serv¬ 
er apps that use the WINSOCK API? Check out http: / /www .catalyst, com, where Catalyst Software offers 
this VBX as a promotional vehicle for their higher end product. They ask you to register the (16-bit) VBX, 
but there's no fee for using it. □ 

Ron Burk 

Editor 

70302.2566@compuserve.com 


Drop in on our brand new Web site! 
You’ll find us at: 

http://www.wdj.com 


You'll find Information and excerpts from 
the current issue, along with links to WDJ 
code, including our SDK Annotations. 
Check it out — and let us know what you 
think. 
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Visual Internet Toolkit 

Save months of TCP/IP programming! 


Fill in properties 


*■ * 


Write a little code 


Distinct FTP OLE Custom Control Properties 


Login | File Transfer | Directoty | 
Host Name: 

Uwt: 

Password 
Account; 

POT: 


I Cancel I Apply 


OLE Custom Controls 

Just ask any OCX jockey. With Distinct’s Visual Internet 
Toolkit, adding TCP/IP connectivity to your application 
is not much farther than a drag-and-drop away. 
Whether you need a customized FTP client or most 
any other Internet application, you can simply embed 
an OCX into your program and Visual Internet 
will do the rest. It’s that easy. And you’ll have 
great looking, powerful applications. 


Protocols 

• Windows Sockets 

• Telnet 

• TCP/UDP/ICMP 

• VT 220 

• PPP/SLIP/CSLIP 

• WinSNMP 

• E-mail/SMTP 

• ONC RPC/XDR 

• POP 2/POP 3 

• rep 

• News/NNTP 

• rexec 

• FTP 

• rlogin 

• TFTP 

• rsh 

• TCP Server 

• And many more 

Interfaces* 

Environments 

• 32 bit (95 and NT) 

• Visual Basic 

• 16 bit (Windows 3.x) 

• Visual C/C++ 

• C++ Class libraries 

• Delphi 

• DLLs 

• C/C++ 

• OCXs 

• Access 

• VBX's 

• FoxPro 



32 Bit Performance 

The power of our new 32 bit Visual Internet Toolkit 
is simply unsurpassed. More custom controls. More 
protocols. More sample code. More Documentation. 
Which makes your job easier and leaves the 
competition in the dust. 


{ 


Call now for 
30 minute 
Internet 
Delivery! 

"I 



Jk ,k . 

distinct 


Tlte world leader in Internet development tools. 


408.366.8933 

World Wide Web: http://www.distinct.r 
Fax: 408.366.0153 

E-mail: windev@distinct.cc 

Fastfacts: 408.366.2101 


*No( all imerfaces may be available for all protocols. Licensii^ fees required for redistribution. Distinct is a registered trademark and 30 minute Intemei Delivery! and Visual Interne! is a mdemaiic of Ihe Distmci Corporation. Copyright 1995 Distina Corporation, 12900 Saratoga Avenue, Saratoga, CA 95070. All rights reserved. Specifications and delhery 
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Memory Management 


A C++ Template for 
Dynamically Allocated Arrays 



Dan Shappir 


= 03 = 

Borland C++ v4.5 

Visual C++ v2.0 


Visual C++ v4.0 


When Windows NT first shipped, programmers were sometimes shocked to dis¬ 
cover that the default stack size for an NT application was 1Mb. That seemed like a 
wastefully large amount of stack space, but in fact, NT merely reserves 1Mb worth of 
virtual addresses for the stack without actually committing physical memory to it. At 
runtime, when your code first accesses an uncommitted page of the stack, it causes a 
page fault that NT handles by committing the physical memory to correspond to that 
page of the stack. In effect, you get the advantage of a huge stack, but you only have 
to pay (in physical memory) for whatever portions of the stack you actually access at 
runtime. 

This ability to use the virtual memory system to create dynamically allocated 
memory regions is not limited to the operating system. Both Windows 95 and 
Windows NT provide API functions that let you perform the same trick in your own 
code. You can create very large arrays that do not use up physical memory except as 
they are accessed; you get the convenience of a large array, but you only pay for 
whatever portion of the array you access at runtime. This article shows how to com¬ 
bine C++ templates and Windows structured exception handling to create dynami¬ 
cally allocated arrays like this for almost any data type. C++ can hide the complexi¬ 
ty of the virtual memory management and make these arrays as easy to use as nor¬ 
mal arrays. The code presented here will work with both Borland and Microsoft C++ 
compilers. 

Virtual Memory 

Each 32-bit Windows process gets a 4Gb flat virtual address space. This does not 
mean that every process gets 4Gb of physical memory. At any given time, some por¬ 
tions of the 4Gb address space may be mapped to physical memory, while others 
may be swapped to disk, and still others may not be mapped to anything — those 
virtual addresses are not valid for your program to use. 

From the hardware's point of view, the 4Gb virtual address space consists of a 
series of "pages" (4 Kb on x86 computers). Each time your program accesses mem¬ 
ory, the hardware uses internal translation tables to locate the corresponding page. 
Each page has attributes that indicate whether the memory is currently swapped to 
disk, is read-only memory, etc. Thus, accessing a virtual address might result in an 
exception, depending on the circumstances. For example, if accessing a particular 
virtual address translates to a page that is currently swapped to disk, an exception 


Dan Shappir holds a B.Sc. in Computer Science and has been a programmer for eight 
years. He is currently working for an Israeli computer firm developing interactive TV 
applications and multi-user games. Dan can be reached on the Internet at 
shapir@math.tau.ac.il. 
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"Sure, NT’s the wave 


Moving to Windows NT is a crucial step for your company. But how do you give up UNIX 
without sacrificing your budget, timelines and quality? Making the transition to a new 
development environment means changing and checking thousands of lines of code, 
usually without the necessary tools or training. 

Essential development tools for programmers 

The move from UNIX to NT doesn’t have to be expensive or time consuming. MKS 
customers do it everyday with MKS Toolkit. Rely on the KornShell on NT to move your 


Now Features: 

* Graphical scripting for Win32 

* Customizable toolbars for Windows 95 

* Enhanced NT security 

* Native 32-bit utilities 


UNIX code over with minimal changes. Only MKS Toolkit’s tape utilities allow you to read * CD ROM 


all your archived information onto your new NT machine, giving you the power to access 
and use stored information. 

The power of UNIX — on your PC 

Fortune Magazine’s top listed companies all use MKS Toolkit. Discover how MKS Toolkit 
can help you leverage your investment in your valuable code base. MKS Toolkit 5.1 is a 
comprehensive suite of 190+ software development utilities for the PC. You’ll find 
powerful new tools such as graphical scripting for Win32, customizable toolbars for 
Windows 95, and enhanced NT security support. 



Now supports Windows 95! (also available for DOS and OS/2) 


(0 1995 MKS and MKS Toolkit are registered trademark of Mortice Kern Systems Inc. All other trademarks 
acknowledged. 

Programmer’s Paradise 800-445-7899 
The Programmer’s Supershop 800-421-8006 
PROVANTAGE 800-336-1166 
Software Spectrum 800-824-3323 
Stream 800-272-4559 


"MKS Toolkit turns Windows NT into a 
world-class set of commands and utilities. 
I wouldn't run without it." 

-Tom Yager 

Open Computing Magazine 

Call today! 

1-800-265-2797 

http://www.mks.com 


MKS 

MORTICE KERN SYSTEMS INC. 


Mortice Kern Systems 
185 Columbia Street West 
Waterloo, Ontario N2L 5Z5 
Main: (519) 884-2251 . 

MKS Germany: ♦ 49 71116714/ 
MKS UK: *44 171 624 0100 
MKS Scandinavia: * 45 33 
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Listing 1 Declarations for dynamically allocated array class 

#ifndef DARRAY H 

protected: 

((define DARRAY H 

static DWORD dwPageSize; // System page size 


static DWORD PageMaskO { return dwPageSize-1; } 

#include <windows.h> 



LPSTR pBase; // Pointer to base of array 

#1f definedC BORLANDC ) 

DWORD dwSize; // Maximum number of pages 

# define TRY try 

DWORD dwTopCommit, dwBottomCommit; 

# define EXCEPT _except 

DWORD dwTopRequest, dwBottomRequest; 

((elif defined! NSC VER) 

BOOL fFai1; 

# define TRY try 


# define EXCEPT except 

virtual LPSTR FromBase(const DWORD) const - 0; 

#endif 

virtual LPSTR ToBase(const DWORD) const - 0; 


virtual DWORD FromOffseUconst DWORD) const - 0; 


virtual DWORD To0ffset(const DWORD) const - 0; 

class CDynamicArrayBase { 

virtual DWORD ToElements(const DWORD) const - 0; 
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Complete Imaging Solutions 
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occurs, and the operating system catch¬ 
es that exception and performs the 
operations necessary to read the page 
back into physical memory. 

The pages comprising a process's 
virtual address space can be in one of 
three allocation states: 

• Tree — The page is not accessible and 
there is no physical storage associated 
with it. A free page is available to be 
committed or reserved. 

• Reserved — The page is not accessible 
and there is no physical storage asso¬ 
ciated with it, but the memory region 
it defines has been set aside for future 
use. This region cannot be used sub¬ 
sequently by other allocation opera¬ 
tions, such as mallocO and 
Local A11 oc (). 

• Committed — The page has physical 
storage allocated to it. It is accessible 
according to the protection assigned 
to it, e.g., read-only access. 

The Win32 API provides a set of virtual 
memory functions that let a process 
manipulate and determine the state of 
pages in its virtual address space. 
Specifically, a process can use 
Vi rtual A11 oc() to reserve and commit 
pages, and Vi rtual Free( ) to release them. 

To implement dynamic arrays in 
your own program, you can use 
Vi rtual A11 oc() to reserve, but not com¬ 
mit, a range of virtual addresses. 
Reserving the virtual addresses does not 
use up physical memory. When you 
later access an address in the range of 
reserved virtual addresses, the hardware 
generates an exception. Your code can 
catch that exception, commit the corre¬ 
sponding memory page (that is, allocate 
physical memory for it), and then cause 
execution to resume as though the 
address had been valid all along. The 
first access to a reserved page of memo¬ 
ry has a high overhead because of the 
code activated by the exception, but all 
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subsequent accesses to that member have 
no extra overhead at all, the same as for 
members of a regular array. 

Here is a tiny example of code that 
uses this technique. Because different 
compilers use different keywords for 
structured exception handling, I use 


macros called TRY and EXCEPT that 
expand into the correct keyword for the 
current compiler. 

int* BigArray; 

// reserve an array of 100,000 ints 
BigArray = (int*) 

VirtualAlloc(NULL, sizeof(int)*100000, 


MEM_RE$ERVE, PAGEJOACCESS); 
TRY { 

BigArraytO] = 45; 

} 

EXCEPT( CommitPage(BigArray, 0) ) 
{ 


Listing 1 continued 

virtual DWORD ToElementsCorrected(const DWORD) const - 0; 

VOID Release(DWORD. DWORD); 

VOID Release!DWORD dwFrom - 0) 

virtual VOID IniUDWORD. DWORD) { ] 

( Release(dwFrom, Size( ) - 1) ; } 

virtual VOID Cleanup(DWORD. DWORD) { } 

DWORD Length!void) const { return ToBytes ( dwSize ) : } 

INT ExceptionHandler(DWORD. DWORD); 

DWORD Size(void) const { return ToElements(LengthO); } 

DWORD PerPage(void)const {return ToElementsCdwPageSize):} 

public: 

): 

BOOL fCommit; 


CDynami cArrayBase!DWORD); 

tempiate<class T> 

-CDynamicArrayBaselvoid); 

class CDynamicArray : public CDynamicArrayBase { 
protected: 

static DWORD ToBytes(const DWORD dwPages) 

LPSTR FromBase(const DWORD dwlndex) const 

{ return dwPages*dwPage$ize; } 

{ return LPSTR(DWORD((T*)pBase+dwIndex) 

static DWORD ToPages(const DWORD dwBytes) 

& -PageMaskO); } 

{ DWORD dwPages - dwBytes/dwPageSize; 

LPSTR ToBase(const DWORD dwlndex) const 

return dwPages+( ToBytes ( dwPages ) < dwBytes ); } 

{ return LPSTR! ( DWORD!(T*)pBase+dwIndex)+sizeof(T) -1) 


& -PageMaskO): } 

virtual DWORD ElementSize(void) const - 0: 

DWORD FromOffset(const DWORD dwlndex) const 


{ return DWORD((T*)pBase+dwIndex) & PageMaskO; } 

BOOL Fail(void) 

DWORD ToOffset ( const DWORD dwlndex) const 

t 

{ return ( DWORD!(T*)pBase+dwIndex)+sizeof(T)- 1) 

if ( fFai 1 ) 

& PageMaskO; } 

{ fFai1 - FALSE: return TRUE; } 

DWORD ToElements(const DWORD dwBytes) const 

return FALSE; 

{ return dwBytes/sizeof(T); } 

j 

DWORD ToElementsCorrected(const DWORD dwBytes) const 

DWORD TopCommit(void) const { return dwTopCommit; ] 

{ return ToElements(dwBytes) 

DWORD BottomCommi t(void) const { return dwBottomCommit: } 

DWORD TopRequest(void) const { return dwTopRequest; } 

+ ( dwBytes%sizeof(T) > 0 ); } 

DWORD BottomRequest(void) const! return dwBottomRequest;} 

public: 


T dummy; 

BOOL Commit(DWORD. DWORD): 
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The code first calls Vi rtual A11 oc() to reserve enough virtual 
address space to hold 100,000 integers. Note that this call only 
reserves virtual addresses, and does not use up physical 
memory. Next, the code accesses some of the newly reserved 
memory. The first time this happens, an exception occurs and 


Listing 1 continued 


CDynamicArray(DWORD dwSize) 

: CDynamicArrayBase(dwSize*sizeof(T)) 

{ 1 

-CDynamicArray(void) { ReleaseO; } 

DWORD ElementSize(void) const { return sizeof(T); } 

T& operator()(const DWORD dwlndex) 

{ return ((T*)pBase)[dwIndex]; } 

T& operator[](const DWORD); 


}; 


T& operatorMvoid) 


{ return (*this)(0); } 


tempiate<class T> 

inline T& CDynamicArray<T>::operator[](const DWORD dwlndex) 

{ 

// The guarded body: 

TRY { 

// Read member bytes to force fault: 

LPSTR p - LPSTR(&(*this)(dwlndex)); 
for ( int i - 0 ; i < sizeof(T) ; ++i ) 
volatile char c - *(p++); 
return (*this)(dwlndex); // Return ref to member. 

} 

EXCEPT ( ExceptionHandler( 

GetExceptionCodeO, dwlndex) ) { 
fFai1 - TRUE; // Mark the failure, 
return dummy; // Return reference to dummy member. 

} 

} 

#endif 

// End of File 
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the exception handler calls the custom function Commi tPage(), 
which presumably will cause the corresponding page to be 
committed. Execution then resumes at the instruction that 
caused the exception. 

This fragment shows the pros and cons of this technique. 
On the one hand, it can be convenient to reserve a large array 
without having to pay for the parts you don't use. On the 
other hand, it can be quite inconvenient to have to surround 
each access to that array with exception-handling code. 
Fortunately, you can use C++ language features to make the 
exception-handling code nearly transparent, as I will show. 

The CDynamicArray Class Template 

darray.h (Listing 1) and darray.cpp (Listing 2) contain the 
interface and the implementation for the CDynamicArray class 
template. CDynamicArray tells the compiler how to generate 
code to implement a dynamically allocated array for a given 
data type. CDynami cAr ray Base is an abstract base class that con¬ 
tains all the code common to all the class types generated from 
the CDynami cArray template; it is independent of the template's 
class argument. The motivation for the distinction between 
code that is dependent upon the class argument and indepen¬ 
dent code is that the template's code is duplicated for every 
class type generated from it. Moving some of the code into 
CDynamicArrayBase, where it only has a single instance, helps 
avoid code bloat. In other words, if you create a dynamically 
allocated array of int and dynamically allocated array of 
f 1 oats, they will share much of the same code (the code sup¬ 
plied by CDynami cArrayBase). To provide a simple and efficient 
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implementation, I have assumed that the page size, in bytes, is 
always a power of two. 

CDynami cArray uses structured exception handling in order 
to catch, and handle, the exception generated by the hardware 
when a member in an uncommitted page is accessed. The 
structured exception handling is implemented using 
Microsoft's frame-based exception-handling syntax. A frame- 
based exception handler consists of a guarded body of code, a 
filter expression, and an exception-handler block. Note that 
this form of exception handling is independent of the 
try/throw/catch exception handling defined by C++. 
Different C and C++ compilers provide access to this 
Windows-specific form of exception handling in different 
ways, as I will describe. 

The guarded body can be a block of 
code, a set of nested blocks, or an entire 
function. In Microsoft C and C++, a 
guarded body is enclosed by braces ({}) 
following the _try keyword. The filter 
expression of a frame-based exception 
handler is an expression that is evaluat¬ 
ed by the system when an exception 
occurs within the guarded body. The fil¬ 
ter expression can query information 
about the exception using the 
GetExceptionCodel ) and 

GetExceptionlnformation( ) functions. 

In Microsoft C++, you write Windows 
exception-handling code like this: 

_try { 

// statements that might cause 
// an exception 

1 

.except ( /* evaluate the exception */ ) 

// code to handle the exception 
// if execution cannot be resumed 
// at the statement that caused the 
// exception. 

1 


system continues to search for a handler. 

EXCEPTION_CONTINUE_EXECUTI ON — The system attempts to 
resume execution at the point at which the exception 
occurred. 

The filter expression is enclosed by parentheses following the 

.except (_except in Borland C++) keyword. The 

CDynami cArrayBase class's member function 
ExceptionHandlerO is used as the filter expression. When 
ExceptionHandlerO is called, it checks the type of the excep¬ 
tion. If the exception is an EXCEPTION.ACCESS.VIOLATION, then 
the page containing the accessed member is committed; oddly 
enough, you use VirtualAllocO to commit pages that were 
reserved by an earlier call to Vi rtual A11 oc(). 

If a different exception activated the filter, or the commit 
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Listing 2 Definitions for dynamically allocated array class 

#1 fndef WIN32 LEAN AND MEAN 

: EXCEPTION EXECUTE HANDLER; 

#define WIN32 LEAN AND MEAN 

} 

#endif 

#1 nclude "darray.h" 

BOOL CDynamicArrayBase::Commit(DWORD dwFrom, DWORD dwTo) 

DWORD CDynamicArrayBase;:dwPageSize: 

l 

II Pointer to first byte to be committed. 

CDynamicArrayBase::CDynamicArrayBase(DWORD dwS) 

LPSTR pFrom - FromBase(dwFrom); 

// Pointer to last byte to be committed. 

LPSTR pTo - ToBaseidwTo)+dwPageSi ze: 

: dwTopCommlt(O), dwTopRequest(0), fCommit(TRUE) 

if ( pFrom < pTo && VirtualAllocipFrom, pTo-pFrom, 

{ 

MEM COMMIT, PAGE READWRITE) ) { 

if ( dwPageSize — 0 ) { 

if ( dwFrom < dwBottomRequest ) 

SYSTEM JNFO Info; 

dwBottomRequest - dwFrom; 

GetSystemlnfoUinfo); // Inquire system page size. 

if ( dwTo > dwTopRequest ) 

dwPageSize - info.dwPageSize: 

dwTopRequest - dwTo: 

) 

dwFrom - ToElementsCorrected(pFrom-pBase); 

dwSize - ToPages(dwS); 

dwTo - ToElements(pTo-pBase-1); 

dwBottomCommit - dwBottomRequest - ToBytes(dwSize); 

if ( dwFrom < dwBottomCommit ) 

pBase - LP$TR(VirtualAlloc(NULL, dwBottomCommit, MEM RESERVE, 

dwBottomCommit - dwFrom; 

PAGE NOACCESS)); 

if ( dwTo > dwTopCommit ) 

fFai1 - pBase — NULL; 

dwTopCommit - dwTo; 

) 

Init(dwFrom. dwTo); // Initialize the range. 

CDynamicArrayBase::~CDynamicArrayBase(void) 

return TRUE; 

} 

( 

return FALSE; 

// Release the pages: 

1 

VIrtualFreetLPVOID(pBase), 0, MEM RELEASE); 

) 

VOID CDynamicArrayBase::Release(DWORD dwFrom, DWORD dwTo) 

INT CDynamicArrayBase::ExceptionHandlerCDWORD dwCode, 

l 

LPSTR pFrom - FromBase(dwFrom)+((FromOffset(dwFrom) > 0) 

DWORD dwlndex) 

? dwPageSize ; 0); 

{ 

LPSTR pTo - ToBase(dwTo)+((ToOffset(dwTo) — PageMaskO) 

return ( fCommit M dwCode -- EXCEPTION ACCESS VIOLATION 

? dwPageSize ; 0); 

U dwlndex < ToBytes(dwSize) M 

if ( pFrom < pTo ) ( 

Committdwlndex, dwlndex) ) 

if ( dwTo >- dwBottomRequest 

? EXCEPTION_CONTINUE_EXECUTI ON 

M dwFrom <- dwBottomRequest ) 
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request fails, the exception-handler block is activated. The 
exception-handler block is enclosed by braces following the 
filter expression. The exception-handler block used by 
CDynamicArray marks the failure and returns a reference to a 
dummy member. The application can detect the failure by 
monitoring the value returned by the Fail () member func¬ 
tion. Fail () returns FALSE when the accessed member is 
already allocated or the allocation was successful; otherwise it 
returns TRUE. Querying the Fa i 1 () member function also resets 
the class's fail state. 

Creating and Accessing Array Elements 

For class types generated from the CDynami cArray template, 
I overload the subscript operator to return a reference to a 
member of the dynamically allocated array. Before returning 
the reference, the member's 
memory is accessed inside the 
guarded body of a frame-based 
exception handler, as described 
above. The following code 
snippet shows how to create 
and access a dynamically allo¬ 
cated array: 


Listing 2 continued 


dwBottomRequest - dwTo+1; 

if ( dwFrom <- dwTopRequest U dwTo >= dwTopRequest ) 
dwTopRequest - dwFrom-1; 

dwFrom - ToEleuients(pFrom-pBase); 

dwTo - ToElementsCorrected(pTo-pBase-1): 

CleanupCdwFrom, dwTo); // Cleanup the range. 

if ( dwTo >- dwBottomCommit 

&& dwFrom <- dwBottomCommit ) 
dwBottomCommit - dwTo+1; 

if ( dwFrom <- dwTopCommit U dwTo >- dwTopCommit ) 
dwTopCommit - dwFrom-1; 

// Decommit pages: 

VirtualFreetpFrom, pTo-pFrom, MEM_DECOMMIT); 


// End of File 


// Create an array with 30000 members 
CDynamicArray<int> iArray(30000); 
for ( int i - 100 ; i <- 200 ; ++i ) 

iArray[i] = i; 

On x86 computers, members 
100 through 200 reside in the 
same page; therefore, only one 
exception will be generated 
and only one memory page is 
committed. There is, however, 
an inherent deficiency in this 
approach. Although accessing 
the memory usedbyiArrayhas 
no more overhead than access¬ 
ing a regular integer array, 
using the subscript operator 
translates to a function call. 
This is because neither Borland 
nor Microsoft C++ compilers 
will inline functions containing 
frame-based exception-han¬ 
dling code. In fact, functions 
containing frame-based excep¬ 
tion handling have more pro- 
log and epilogue code then do 
functions with no exception 
handling. 

I wanted to provide an 
alternative syntax for accessing 
array elements — one that did 
not require the overhead of a 
call to separate function con¬ 
taining exception-handling 
code. Therefore I overloaded 
the function call operator to 
perform unmonitored access to 
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the array, which means you can write code like this: 

CDynamicArray<int> iArray(30000); 
iArray[27] - 999; // slow but safe 
iArray(27) = 999; // fast, but be careful 


After a range of memory has already been committed, it is 
possible to access the range with no extra overhead. For exam¬ 
ple, after the previous code snippet has been executed, access¬ 
ing members 100 through 200 doesn't require validation, and 
the following code can be used: 


Listing 3 Demonstration of dynamically allocated array class 

(/include <iostream.h> 

public: 

(/include (string.h> 

foo(void) { } 

(/include "darray.h" 

foo(const int value) { *this - value; } 

foo& operator-(const int value) 

{ memcpy(bar, &value, 3); return *this; ) 

// Derive a class from CDynamicArray: 

operator into const 

class CIntArray : public CDynamicArray<int> { 

{ int value; memcpy(&value, bar, 3); 

protected: 

return (value << 8) » 8; } 

VOID Init(DWORD. DWORD); // Override default InitO 

); 

public: 

#if defined(_MSC_VER) 

CIntArray ( DWORD size) : CDynamicArray(intXsize) { } 

(/ pragma packO 

}; 

(/elif defined(_B0RLANDC ) ) 

(/ pragma option -a 

VOID CIntArray::Init(DW0RD from. DWORD to) 

(/end if 

for ( DWORD i - from ; i <- to ; ++i ) 


(*this)(i ) - i; 

// Access dynamically allocated array members with no 

i 

// exception monitoring: 
void Init(CIntArray& iArray ) 

// Define a three byte class object: 

iArray.Commit(0, 19999); 

#if defined! MSC VER) 

for ( int i - 0 ; i < 20000 ; ++i ) 

(/ pragma pack(l) 

iArray ( i ) - -i; 

#el 1 f def 1 ned(_B0RLANDC_ ) 

) 

(/ pragma option -al 


(/end if 

// Access dynamically allocated array members with exception 
// monitoring: 

class foo { 

void Print(CIntArray& iArray ) 

char bar[3]; 

i 
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for ( i = 100 ; i <= 200 ; ++i ) 
iArray(i) = -i; 

Because the function call operator does not use exception 
handling, it can be inlined. The compiler will generate an 
instruction sequence that is identical to that generated for 
accessing a regular array. Care must be taken, because unmon¬ 
itored access of members that have not been committed will 
cause the program to crash with a page fault. 

Committing and Releasing 

The CDynami cArray class template also provides member 
functions for explicitly committing and releasing (decommit¬ 
ting) memory pages. The Commit () member function is called 
by Excepti onHandl er ( ) whenever new pages are required. It is 
also possible to call CommitO explicitly, specifying the array 
range to be committed. Note that in most cases the array range 
actually committed will be larger than that requested. That is 
because memory is committed in units of one page (4Kb on 
Intel machines), so, for example, if you commit a range of ele¬ 
ments that happens to start in the middle of a page, that entire 
page gets committed. Likewise, when the range of elements 
you are committing ends in the middle of a page, that entire 
page is also committed. Commit () returns a Boolean value. A 
TRUE return value indicates successful allocation of all the 
requested array members. A FALSE return value indicates fail¬ 
ure. Committing memory pages that have already been com¬ 
mitted has no undesirable effects. 

The Release!) member function can release the memory 
pages used by array members that are no longer required. 
Those pages will still be reserved, but they will no longer use 
any physical memory. Unlike Commit! ), Rel ease! ) is activated 
only by an explicit call. As with Commit! ), the range of array 
members released will, generally, not be identical to the range 
requested. In this case, only memory pages that are entirely 
within the range are decommitted. The Release!) member 
function has three flavors. Releasetfrom, to) attempts to 
release the memory used by the members between from and 
to, inclusive. Releasetfrom) attempts to release the memory 
used by members starting at from to the end of the array. 
Rel eased attempts to release the memory used by the entire 
array. All flavors of Release!) return a Boolean value, with 
TRUE indicating successful deallocation and FALSE indicating 
failure. Decommitting a page that is already uncommitted has 
no undesirable effects. The CDynami cArray destructor automat¬ 
ically calls Release! ). Note that you will lose any data that 
was in the pages you released. 

Both the Commit! ) and Rel ease! ) member functions update 
the values of CDynamicArrayBase class members that indicate 
the limits of the array range that was requested, and the range 
actually committed. As explained earlier, these ranges are not 
identical. The limits for the allocated range can be queried 
using the BottomCommit! ) and TopCommit! ) member functions. 
The requested range can be queried using the BottomRequest ( ) 
and TopRequest! ) member functions. Note that because these 
values are updated only by explicit calls to Commit!) and 
Release!), and by exceptions, the values returned by 
TopRequest!) and BottomRequest!) don't reflect accesses to 
implicitly allocated members outside the requested range. 


Member Initialization and Cleanup 

When CDynamicArrayBase::Commi t() is called to commit 
pages, it calls the virtual member function I n i t (). The default 
version of InitO, defined in CDynamicArrayBase, does noth¬ 
ing, but you can override this function in a derived class to 
perform array member initialization. Init!) takes two para¬ 
meters. The first parameter is the index of the first member in 
the committed range. The second parameter is the index of 
the last member in the committed range. Because Init!) is 
invoked after the call to Vi rtualAl loc! ), it is possible to access 


Listing 3 continued 


for ( int i - 0 ; i < 100 ; ++i ) { 
int temp - iArray[i+1000]; 
if ( iArray.Fail 0 ) 
return; 
if(i — 23) 

cout « "oh oh 
cout « temp « ' 

} 

} 

int main(void) 

{ 

CIntArray iArray(30000): 

cout« "Elements per page: " « iArray.PerPage() « *\n'; 

Init(iArray); 

Print(iArray); 

cout«"\nRequested range: " « iArray.BottomRequest() « 

" - " « iArray.TopRequest() « '\n'; 
cout« "Committed range: " « iArray.BottomCommit!) « 

" - " « iArray.TopCommit() « '\n'; 

iArray.Release(50); 
iArray.fCommit - FALSE; 

Print(iArray); 

cout« "\nRequested range: " « iArray.BottomRequestO « 
" - " « iArray.TopRequestO « ’\n’; 
cout« "Committed range: " « iArray.BottomCommitO « 

" - " « iArray.TopCommitO « '\n'; 

iArray.fCommit - TRUE; 

Print(iArray); 

cout« "\nRequested range: " « iArray.BottomRequest() « 
" - " « iArray.TopRequestO « '\n'; 
cout« "Committed range: " « iArray.BottomCommitO « 

" - " « iArray.TopCommitO « '\n'; 
cin.getO; 
iArray. ReleaseO; 

// Use a dynamically allocated array as an argument for 
// a function that expects a regular array: 
CDynamicArray<char> cArray(256); 

LPSTR Ipsz - "String"; 
cArray.Commit(0, strlendpsz)); 
strcpy(&(*cArray), lpsz); 
cout « LPSTR(&(*cArray)) « '\n*; 

// Because 4096 is not divisible by 3 one member will 
// reside in two pages: 

CDynamicArray<foo> fooArray(30000): 

DWORD dwPerPage - fooArray.PerPageO; 
fooArray[dwPerPage] - sizeof(foo); 
cout « fooArray[dwPerPage] « '\n*; 
cout« "Requested range: " « fooArray.BottomRequestO « 
" - " « fooArray.TopRequestO « *\n'; 
cout« "Committed range: " « fooArray.BottomCommitO « 

" - " « fooArray.TopCommitO « '\n*; 

fooArray.fCommit - FALSE; 

fooArray.dummy - -17; 

cout « fooArray[20000] « *\n'; 

cout« "Requested range: " « fooArray.BottomRequestO « 
" - " « fooArray.TopRequestO « *\n*; 
cout« "Committed range: " « fooArray.BottomCommitO « 

" - " « fooArray.TopCommitO « '\n’; 
cin.getO; 

return 0; 

} 

// End of File 


April 1996 


Windows Developer’s Journal — Page 17 







Listing 4 Problems with Visual C++ 


finclude <iostream.h> 

tempiate<cl ass T> 
class too { 

T array[100]; 

public: 

T& operator[](const int i) { return array[i]; ) 
operator T*() { return array; ) 

}; 

// foo<int> dummy; // Uncomment to turn off Visual C++ v2.0 bug. 

void Proc(foo<int>& bar) 

{ 

bar[0] - 1; 

unsigned index = bar[0]; 

bar[index] = 2*index; // This line causes second bug. 


int main(void) 

{ 

foo<int> bar; 

Proc(bar); 

cout << bar[0] « ' ' « bar[l]; 
return 0; 

} 

// End of File 
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the array members without exception handling. Care must be 
taken when designing the initialization code because, when 
activated by an explicit call to Commi t(), the range may include 
members that have already been committed. Reinitializing 
these members is inefficient and may be destructive. 

The ReleaseO member function calls Vi rtualFree () to 
decommit pages, but it first calls the Cl eanup( ) virtual mem¬ 
ber function. The default Cl eanup () member function, defined 
in CDynamicArrayBase, does nothing. Like InitO, CleanupO 
can be overridden to perform cleanup operations on array 
members before their memory is released. CleanupO is 
invoked with two parameters, specifying the indices of the 
first and last members in the range to be released. Note that 
the range may include holes, i.e., members residing in pages 
that have not been committed. Therefore, accessing the range 
without exception handling might cause the program to crash. 
Accessing the range using the monitored overloaded sub¬ 
script operator will work, but will have the undesirable effect 
of allocating and initializing the entire range only so that it can 
be cleaned up and released! It is possible to avoid this situa¬ 
tion by using the f Commit member of CDynamicArrayBase. 
f Commit is a Boolean member initially set to TRUE. Setting its 
value to FALSE instructs ExceptionHandl erf ) to always fail 
(return the value EXCEPTION_EXECUTE_HANDLER). The first mem¬ 
ber in every page in the range is read with committing turned 
off. If the page is committed, Fai 1 () will return FALSE. If the 
page is only reserved, Fa i 1 () will return TRUE and the page can 
be skipped. 

If you are creating a class that provides a dynamically allo¬ 
cated array of objects of a user-defined class, you can override 
the InitO and CleanupO member functions to explicitly 
invoke the members' constructor and destructor. If foo is a 
dynamically allocated array of bar type objects, the syntax for 
invoking the constructor, inside foo's InitO member func¬ 
tion, is: 

(*this)(i).bar: :bar(...); 

Likewise, you can invoke the destructor, inside CleanupO, 
with: 


(*this)(i).bar::~bar(); 

Extra care must be taken to avoid calling the constructor or the 
destructor twice for the same object. 

Passing Dynamically Allocated Arrays 

A major advantage of dynamically allocated arrays over 
alternative data structures is that a pointer to a dynamically 
allocated array's member can be passed as an argument to a 
function that expects a pointer to a regular array of elements 
of this type. This is true for the C and C++- runtime library 
functions, such as the functions defined in stri ng. h, as well as 
for user-defined functions. This is possible because once a 
range of members in a dynamically allocated array as been 
allocated, it is stored exactly like a regular array. If, however, 
the activated function attempts to access a member that has 
not been allocated, the program will crash. To avoid this, allo¬ 
cate the array range that the function might access before call- 
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ing the function. For example, before using a dynamically 
allocated array of characters as the target for StrcpyO, use 
StrlenO to determine the length for the source string, and 
then call Commit() to allocate that number of members, plus 
one for the terminating NULL character. 

A more robust solution is to place the function call inside 
the guarded body of a frame-based exception handler. When 
an exception occurs, call Commit! ) and resume execution at the 
point where the exception occurred. There is a problem with 
this approach, however: how to determine which unallocated 
member of the array caused the exception. A user-defined 
function can store the index of the member it is attempting to 
access in a global variable. The exception handler's filter 
expression will call Commit! ) with that index value. When it is 
not possible to extract the index value from the function, there 
is another alternative. If the function accesses the array's 
members in a sequential order — e.g., memcmp! ) — the solution 
is to commit one page at time until no more exceptions are 
generated. 

test.cpp (Listing 3) shows an example of exercising the 
features of these classes. The code shows how to derive a new 
class in order to override the Init!) function and handle ini¬ 
tialization. It also demonstrates explicit calls to commit and 
uncommit memory, and how to pass a dynamically allocated 
array of characters to an ordinary runtime library function. 

Visual C++ Bugs 

During the development of the CDynamicArray class tem¬ 


plate, I came upon two bugs in Microsoft's Visual C++ 2.0. The 
code in bug. cpp (Listing 4) compiles under Watcom C++ vlO.O 
and Borland C++ v3.1, and in both cases, the resulting exe¬ 
cutable ran properly. Visual C++ v2.0 generates the following 
error during compilation: 

error C2676: binary ’[’ : ’class foo<int>’ 
does not define this operator or a 
conversion to a type acceptable to 
the predefined operator 

Apparently, using a reference to class object, based on the tem¬ 
plate, does not prompt Visual C++ to actually generate the 
class from the template. Using the template-based class in any 
other way before Proc( ) is defined — e.g., defining a global 
variable of the same type — solves the problem. It is even suf¬ 
ficient to transfer the parameter to Proc! ) by value instead of 
by reference. This bug appears to be fixed in Visual C++ v4.0. 

After you work around that bug, another immediately aris¬ 
es: 

error C2666: ’[]’ : 2 overloads have 
similar conversions 

This error is generated for the expression: 

ba r[index] = 2*index; 

Note that the overloaded subscript operator accepts an integer 
parameter. The variable index, however, is an unsigned inte¬ 
ger. As result, Visual C++ can't decide whether to convert 
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index from unsigned to signed and use the subscript operator, 
or use the overloaded conversion operator to translate the 
object reference into a pointer to its first element and use 
pointer arithmetic. Although in this case both choices would 
achieve the same goal, I believe the first choice is the correct 
one, and indeed it's the one both Watcom and Borland use. 
Visual C++ v4.0 still contains this behavior. 

The first bug makes the use of the CDynami cArray template 
(or of any template in fact) a bit more awkward. The second 
bug prevented me from making CDynami cArray-generated 
classes appear more array-like, by defining a conversion oper¬ 
ator to translate a reference to a CDynami cArray-generated class 
into a pointer to its first member. I did, however, define the 
unary indirection operator, *, to return a reference to the first 
member of the array, so that, for a CDynami cArray object foo, 
*foo is identical to foo[0] (actually to foo(0) because no 
exception monitoring is performed). 


A Warning Message 

When a program is run from inside the Visual C++ IDE, it 
is activated as a process being debugged. The system informs 
the IDE of all debug events that occur in the debugged 
process, and these include the exceptions generated when an 
unallocated member of a dynamically allocated array is 
accessed. As result, when a program that uses the 
CDynami cArray class template is run from inside the Visual C++ 
v2.0 IDE or inside the Microsoft Developer Studio, expect to 
see the following message in the debug window after the pro¬ 
gram terminates: 
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file2 
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file2 
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filel 
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First-Chance Exception in 
... .exe: 0xC0000005: Access Violation. 

Don't worry, this is just a notification. When the program is 
run as a standalone application, the user will have no inkling 
of the exceptions taking place, and being handled, inside. 

Summary 

The CDynami cArray class template is an example of the ben¬ 
efits derived from combining the capabilities of the operating 
system and the programming language. The Win32 API 
enables management of memory objects based on the hard¬ 
ware's capabilities, and that has many advantages over alter¬ 
native software-based solutions. The C++ language, with its 
inherent abstraction capabilities, allows the implementation of 
complex data structures with an interface that mimics that of 
a simple array. The combination of the two facilitated the cre¬ 
ation of the dynamically allocated array generic type. 
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Memory Management 


Don’t Use Memory-Mapped Files 

Ron Burk 



Windows 95 contains an implementation of memory-mapped files, allowing 
Windows programmers to treat disk files as an extension of virtual memory. The 
technical press is encouraging programmers to make extensive use of memory- 
mapped files for all kinds of applications; rarely does anyone point out the wide 
variety of problems for which memory-mapped files are an absolutely terrible solu¬ 
tion. In this article, I will discuss why some recommendations on when to use mem¬ 
ory-mapped files are completely wrong, and how to intelligently decide when this 
new tool makes sense. 

Stirring up Trouble 

This article was really inspired by Jeffrey Richter, the talented programmer who 
wrote the book Advanced Windows, among other things. In an article that appeared 
in the October 1995 Microsoft Systems Journal, he wrote: "Windows 95 and Windows 
NT make it possible to memory map a 500Mb database file that you can then sort 
with a single call to the C run-time's qsort function." In my December 1995 editori¬ 
al, I poked a bit of fun at the absurdity of this particular application for memory- 
mapped files with the flip comment "Can you say 'thrashing'?" Feedback from that 
comment made me realize that this topic is worthy of more than just an offhand joke. 
Arriving at a good mental model for memory-mapped files takes a bit of thought if 
you've never been exposed to such a facility before. 

One of the most telling responses to my editorial comment came from an alert 
reader named Axel Rietschin. Axel had some good comments about other parts of 
our December issue, and he also said this: 

You miss the point about memory mapped files (MMF). In fact, mapping an arbitrary 
sized (<2Gb) file in a process memory space is virtually instantaneous. The file is not 
loaded at all. A MMF is just a special kind of paging file. If you can write a few lines of 
C code, I encourage you to try the MSJ qsortt) example and compare it to any other 
method for disk-based sorting. You will probably end up with 1/10 of the code and 1/10 
of the run time using MMFs. 

Like most programmers, I often engage in the sinful pastime of arguing about effi¬ 
ciency without ever making a single measurement. However, a challenge like this 
one was all I needed to overcome my natural inertia, and I sat down to perform a lit¬ 
tle benchmark. Would Alex and Jeffrey be proved right? Clearly, what was intu¬ 
itively obvious to me was not obvious to everyone else, so a benchmark was the 
quickest way to move the discussion to a higher plane. 


Ron Burk is the editor of Windows Developer's Journal and has been a programmer 
for 12 years. You may contact him at 70302.2566@compuserve.com. 
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A Sanity Check 

First, I wrote a trivial program to generate arbitrarily sized 
dummy databases of fixed-length records. The code for this 
program is supplied on our code disk (see Table of Contents 
for availability) for anyone interested, but it simply uses the 
rand() function to generate random lines of ASCII text, com¬ 
posed only of alphabetic characters and terminated with a 


CR/LF. You pass this program two numbers: the length of 
record you want and the number of records to generate. I used 
the program to generate a "database" of records, each 80 bytes 
long (78 random alphabetic characters, followed by CR/LF). 

Second, I wrote a program that followed Richter's advice 
to map the database into memory and then perform a qsort() 
on it. The program is in qsort.c (Listing 1) and is short, both 
because of the brevity of the technique and because of the 

complete lack of error check¬ 
ing. As both Richter and the 
reader suggested, this code 
does an awful lot with only a 
few lines of code. But is it a 
reasonable technique for sort¬ 
ing large amounts of data? 
Would it really be an order of 
magnitude faster than those 
hoary old techniques for disk- 
based sorting, as the reader 
suggested? Or would it be the 
dog-slow, disk-thrashing dis¬ 
aster I expected? 

Third, I grabbed a disk- 
based DOS sorting utility off 
CompuServe, just to do a 
quick sanity check of my own 
engineering judgment. I creat¬ 
ed a database of one million 
records (80Mb) and sorted it 


Listing 1 qsort.c — Using qsortQ with memory-mapped files 


InFile - CreateFile(argv[l], GENERIC_WRITE | GENERIC_READ, 0, 
NULL. OPENJXISTING, 0. 0); 
if(!InFile) 

{ 

fprintf(stderr. “Can’t open ‘Xs’Vn". argv[l]); 

Usage!); 

} 


#include <stdio.h> 
#include <stdlib.h> 
include <stdarg.h> 
#include <windows.fi> 


const char* INPUTFILE-~memfile.dat"; 

void Usage(void) 

{ 

fprintf(stderr, 

“Usage: qsort <fi1ename> <RecordSize> <nrecords>\n”); 
exit!EXIT_FAILURE); 

} 

int Compare(const void*a, const void*b) 

{ return strncmp!a.b.78); } 

void main!int argc, char** argv) 

{ 

int RecordSize, NRecords; 

HANDLE InFile. Map: 
void* Mem: 

if(argc !- 4) 

Usage!); 


RecordSize - atoi(argv[2]); 

NRecords - atoi(argv[3]); 
if(RecordSize <- 0 || NRecords <- 0) 

Usage!); 

Map - CreateFileMapping!InFile. 0. PAGE_READWRITE, 0. 
RecordSize*NRecords. 0): 

Mem - MapViewOfFi1e(Map. FILE_MAP_WRITE, 0. 0. 0): 

qsort(Mem, NRecords, RecordSize. Compare); 

FIushViewOfFi1e(Mem. 0); 

UnmapViewOfFi1e(Mem); 

CloseHandle(Map); 

CloseHandle(InFile); 
exit!EXIT_SUCCESS); 

) 

/* End of File */ 
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Table 1 How inefficient are memory- 

mapped files? 

File size 

memory-mapped file 

simple disk-based sort 

16 Mb 

0.85 minutes 

.50 minutes 

32 Mb 

3.15 minutes 

1.15 minutes 

80 Mb 

12.65 minutes 

3.17 minutes 

250 Mb 

94.77 minutes 

11.50 minutes 


with the DOS utility. But before I ran the DOS utility, I crip¬ 
pled it by giving it a DOS shell with no access to extended or 
expanded memory — that meant that the disk-based DOS 
utility would have less than 640Kb of memory to compete 
against the modern technique of memory-mapped files, with 
access to nearly 50 times as much memory (my machine has 
32Mb of physical memory). What do you think happened? 

In fact, the crippled DOS utility was able beat the memory- 
mapped file algorithm by about 10 percent! Satisfied that no 
surprises awaited me, I sat down to write a more realistic 
benchmark. 

A Real Comparison 

To provide a more realistic demonstration of how poor a 
choice memory-mapped files can be, I wrote a simple disk- 
based sort utility that took advantage of the available memo¬ 


ry on my machine. A basic merge-sort works by reading a 
large chunk of the input file, sorting it, writing it to a tempo¬ 
rary file, reading the next chunk, sorting it, writing that to 
another temporary file, and so on. After the input file has been 
split into a number of sorted temporary files, the merge 
begins: the program reads the first record from each tempo¬ 
rary file, finds the smallest record by sort order, then writes it 
to the output file. Of course, a professional sort algorithm does 
much better than this, but I was content to use just this crude 
algorithm — however, I allowed it to process 16Mb chunks of 
data at a time, taking reasonable advantage of the physical 
memory on my machine. The result was by no means a gen¬ 
eral sort algorithm, but it worked fine for this benchmark. The 
code is unremarkable (and not terribly clean), so it is not 
reproduced here (you can get it off the code disk if you're 
interested). All I wanted was a rudimentary disk-based sort 
program that could take advantage of as much memory as 
was available. 

After I wrote the basic sort-merge utility, I started generat¬ 
ing databases of random data, then sorting them. First, I sort¬ 
ed with the sort-merge utility, then I sorted with the memory- 
mapped file algorithm. Table 1 shows the results for the data¬ 
base sizes I tried. I did not have enough disk space to sort the 
500Mb database mentioned in Microsoft Systems Journal, but as 
you can see from the table, that would have required a lot of 
patience to measure anyway! Interestingly, the memory- 
mapped file approach was worse even for data that should 
have fit easily in the available physical memory — if that 
seems inexplicable, the rest of this article should give you some 
clues as to why it's not that surprising. 

What Went Wrong? 

Why would some knowledgeable 
programmers have predicted the 
wrong outcome for this benchmark? I 
think there's just a natural tendency 
among programmers to grab any neat 
new tool and try to apply it to all sorts 
of things before completely under¬ 
standing how it works and what it's 
good for; I know that happened to me. I 
first used memory-mapped files a year 
or two before Microsoft started creating 
the Win32 API. We were creating an 
electronic funds transfer (EFT) applica¬ 
tion on a fault-tolerant Stratus comput¬ 
er under the VOS operating system, 
which supplied a reasonably modem 
API that included memory-mapped 
files. Memory-mapped files seemed like 
such a great idea that, even though we 
were strapped for time, I carefully 
structured my code so that we could 
switch to using memory-mapped files 
in the future — and presumably get a 
free boost in speed. When I finally had 
time to flip the compile-time switch, 
enable the conditional code, recompile, 
and benchmark our software using 
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memory-mapped files, I was very disappointed to discover no 
speed-up whatsoever. That's when I had to sit down and 
think hard about what memory-mapped files are good for, 
and what they aren't good for. 

The place to start is by understanding what memory- 
mapped files are, so I'll give a crude description. Operating 
systems typically implement virtual memory by creating a 
large file and using it as storage for those parts of virtual 
memory that cannot currently fit in the (typically much small¬ 
er) available memory. When your program references an 
address not currently represented in physical memory, the 
operating system has to free up some physical memory (by 
writing it to the corresponding position of the large file), and 
then read the previous state of that memory back into the 
newly available position in physical 
memory. Your program gets the luxury 
of being able to pretend that large 
amounts (e.g., gigabytes) of memory 
are available, but with the penalty that 
the mere act of accessing a memory 
address may incur disk I/O. 

Memory-mapped files are a general¬ 
ization of this standard swapping 
mechanism for virtual memory. Since 
the operating system already knows 
how to map virtual addresses to its own 
internal swap file, why can't it give you 
the same ability? Memory-mapped files 
let you specify that any ordinary file of 
your choosing be mapped to a range of 
virtual memory addresses. As the read¬ 
er letter pointed out, the act of mapping 
the file does not necessarily cause any 
disk I/O to occur — only when you 
access an address in the range of 
mapped virtual memory does the oper¬ 
ating system have to go out and read 
the corresponding portion of the file 
into physical memory. When you store 
data in an address in the range of 
mapped virtual memory, the operating 
system does not have to immediately 
write the data back to disk; your data 
may not be written back to the mapped 
disk file until the file is closed, or until 
the operating system needs to free up 
some physical memory. 

In thinking about memory-mapped 
files, it's important to have a feel for the 
overhead of disk I/O. Despite the fact 
that hard disks continue to get smaller, 
faster, and cheaper, they remain incred¬ 
ibly slow compared to the speed with 
which the CPU executes machine 
instructions. For example, the machine 
I'm using right now can write a 4KB 
page of data to disk in about 1.2 mil¬ 
liseconds. In that same amount of time, 
the same machine was able to execute 
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75,000 iterations of a loop that incremented an integer. Think 
about tapping your foot 75,000 times each time you need to 
store something on disk, and you start to grasp just how slow 
the disk is relative to the CPU. That leads fairly directly to an 
understanding of why memory-mapped files can be a bad 
choice for many situations. If your program accesses large 
disk files, it is usually crucial to structure the program in a 
way that minimizes the number of disk 1/Os required. 

Disk I/O Is Slow 

The main reason to avoid memory-mapped files is that 
disk I/O is slow. No, make that incredibly slow, compared to 
the speed of the CPU. Consider the poor qsort( ) applied to a 
memory-mapped file. The author of qsort () no doubt did a 
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quite competent implementation. The problem is, the qsort() 
algorithm was written with the assumption that the cost of 
accessing any particular record in the data was the same as the 
cost of accessing any other record in the data — negligible. 
Unfortunately, when you apply qsort () to a memory-mapped 
file that is larger than physical memory, you guarantee that the 
cost of accessing some records will be hundreds of thousands 
of times larger than the cost of accessing other records (those 
that are already swapped into physical memory). qsortO's 
goal is to minimize the number of exchanges, not to minimize 
the number of accesses to each record. Therefore, you don't 
really have to know a lot about the details of how a quicksort 
is implemented to reason that it's not likely to fare well when 
applied to memory-mapped files instead of physical memory. 


Physical Memory Still Matters 

The fact that the operating system lets you map a huge file 
into virtual memory does not change the fact that you have a 
limited (and usually much smaller) amount of physical mem¬ 
ory. Memory-mapped files have no special magic that can 
alter this. So, it should be clear that if you're going to map a 
500Mb database into virtual memory, but you only have 32Mb 
of physical memory, you still have to carefully plan how you 
access the data if you want to avoid a whole lot of (very slow) 
disk I/O. It's no quicker to sequentially access a memory- 
mapped file than to sequentially read a file. 

Virtual Memory Is Not Infinite Memory 

The third reason to avoid memory-mapped files is that vir¬ 
tual memory is not infinite. Your oper¬ 
ating system may give you a large vir¬ 
tual address space to play with (say, 
2Gb), but would you really want a data¬ 
base program that could never sort files 
larger than 2Gb? Also, would you want 
a library function that used up large 
chunks of your virtual address space 
just to make its own coding simpler? 

If the file you are dealing with is 
sequential in nature, then plain old file 
I/O is still a very good choice. With 
normal sequential reads and writes, 
your algorithm ends up being limited 
only by available disk space, not by 
available virtual memory address 
space. Also, a good operating system 
will often cache disk I/O in a way that 
optimizes sequential I/O, giving your 
program a free speed-up without any 
extra coding on your part. Sequential 
I/O also tends to require less physical 
movement of the disk heads, which 
helps explain why using memory- 
mapped files was slower even when the 
database fit entirely in physical memory. 

The O/S Cache Is Dumb 

The operating system tries to cache 
disk-based data for you in order to 
speed things up. For example, if you 
read the first page of a file into memory, 
rewind, then read the first page into a 
different address in memory, the oper¬ 
ating system will most likely not have 
to perform a disk access to retrieve the 
data the second time; it will still be in an 
operating system cache. Unfortunately, 
the operating system has little knowl¬ 
edge about how any particular program 
will access a disk (or virtual memory 
addresses). Instead, the operating sys¬ 
tem has to make crude guesses. It 
guesses that if you just read the first 
page of a file, you might next read the 
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second page. It guesses that if you just accessed virtual mem¬ 
ory location 0x80001000, then there's a reasonable chance you 
might access it again before too long. As you might expect, the 
operating system often guesses wrong, resulting in disk 1/O. 

There's a simple rule of thumb you can use when consid¬ 
ering the caching that the operating system does for you: for 
any given program, you can almost always design a better cache 
than the one the operating system provides. That's one way to 
view what went wrong with the qsort () benchmark. In using 
qsortt ) with memory-mapped files, you're really saying that 
the caching provided by the operating system will be ade¬ 
quate. In fact, the operating system's caching is almost worth¬ 
less for the nearly random pattern of accesses that qsortt) 


makes to memory. You can view the disk-based sorting algo¬ 
rithm as a more intelligent way to cache data during the sort¬ 
ing process. 

When you use memory-mapped files, you are putting 
yourself at the mercy of the operating system's caching algo¬ 
rithm. If your pattern of access really has to be random, or 
nearly so, then the operating system's cache will probably do 
as well as any you could write. For most programs, though, 
you could achieve better efficiency with normal disk 1/O and 
your own custom caching code. 

Memory-Mapped File I/O Is Synchronous 

Yet another good reason to avoid memory-mapped files is 
that you surrender the ability to directly take advantage of 
asynchronous I/O. Windows 95 does 
not support asynchronous disk I/O, but 
NT does. If I were designing a really 
fast sort utility that ran under NT, I 
would read in the first chunk of data, 
then start an asynchronous read to read 
in the next chunk. While that asynchro¬ 
nous read was completing, I would 
have plenty of time to get the first 
chunk sorted and ready for output 
(which could also be asynchronous). 
With a memory-mapped file, you don't 
have a whole lot of control over which 
memory access is going to result in a 
disk I/O, and when that happens, your 
thread will be stopped cold until the 
I/O completes (i.e., it will be tapping its 
foot 75,000 times when it could have 
been doing something useful). 

Summary 

The title of this article is somewhat 
tongue-in-cheek. There are certainly sit¬ 
uations for which memory-mapped 
files are a good thing to use. They are 
the fundamental mechanism under 
Windows 95 and Windows NT for 
shared memory. They can provide an 
efficient and easy-to-code method for 
truly random access to a large file. But, 
like other features of the Win32 API 
(such as multithreading), they have all 
too often been touted for completely 
inappropriate tasks. Think carefully 
about what a memory-mapped file real¬ 
ly is before you use one, especially if the 
file being mapped is significantly larger 
than the available physical memory. 
Don't get caught producing software as 
incredibly inefficient as that portrayed 
in Table 1 just because someone said 
you should be using memory-mapped 
files! □ 
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Displaying System Messages 


Paula Tomlinson 
paulat@microsoft.com 

I've seen many developers duplicating strings in their own code to describe the 
standard Windows error messages. These strings are already defined by the operat¬ 
ing system and you can retrieve them with the little-known but useful 
FormatMessaget ) routine. An added benefit of this technique is that these strings exist 
in the local language of the operating system, so you don't need to localize them 
yourself in order to support multiple languages. 

The sample program in sysmsg.cpp (Listing 1) exercises a utility routine, 
Di spl aySystemMessaget ), that I use often in my own code. It displays a message box 
based on the system error passed in. If a window handle is also passed in, then it is 
used as the parent window of the message box. To demonstrate processing an error, 
I attempt to open a file that I know does not exist. 

FormatMessaget ) has many uses and is thus a somewhat complicated routine. If 
you want FormatMessaget ) to retrieve standard error message descriptions, then you 
must specify the FORMAT_MESSAGE_FROM_SYSTEM flag in the first parameter. You can also 
specify FORMAT_MESSAGE_ALLOCATE_BUFFER if you want the routine to allocate a suffi¬ 
ciently sized buffer, but I chose to supply my own character array. FormatMessaget) 
can handle formatted strings by using insert sequences in much the same way that 
sprintf () uses “%s” or “U", for example. Since I won't be specifying any insertion 
arguments, I use the FORMAT_MESSAGE_IGNORE_INSERT flag to tell FormatMessaget) to 
ignore the Arguments parameter. The dwMessageId parameter is simply the value 
returned from GetLastError (). The other interesting parameter is dwLanguageld. The 
language ID is formed from a language value and a sublanguage value. The neutral 
definitions instruct FormatMessaget ) to use whatever language is the default for this 
installation of the operating system. 

Once I've retrieved the text associated with the system error, I simply display it 
in a message box. In my example, the last error set happens to be 
ERROR_FI LE_NOT_FOUND and the system-defined message string is "The system cannot 
find the file specified." The D i spl aySystemMessage () routine was tested on both 
Windows 95 and Windows NT using the MS VC compiler. 

Detecting if CTL3D Has Subclassed a Window Procedure 


V.Ramachandran 
Madras, India 
raja@imagine.uunet.in 


The 3D effects for dialog boxes in Windows 3.x applications was provided by a 
DLL called Ctl3d.dll. This was developed by the Microsoft Excel team, and later 
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Listing 1 sysmsg.cpp 


//include <windows.h> 

VOID DisplaySystemMessage(HWND hWnd, UINT uiSystemError); 

TCHAR pszErrorCaption[] - TEXTC'System Message Sample Program"); 

//. 

VOID main(VOID) 

{ 

HANDLE hFile - NULL; 

hFile - CreateFile(TEXT("x.x"), GENERIC.READ, 0, NULL. 0PEN_EXISTING. 

FILE_ATTRIBUTE_NORMAL, NULL); 

DisplaySystemMessage(NULL, GetLastError()); 
if (hFile !- NULL) CloseHandle(hFi1e); 
return; 

} // main 


// 


VOID DisplaySystemMessage(HWND hWnd. UINT uiSystemError) 

{ 

TCHAR szMessage[MAX_PATH]; 

// retrieve the string matching the Win32 system error 
FormatMessage( 

FORMAT_MESSAGE_IGNORE_INSERTS | FORMAT_MESSAGE_FROM_SYSTEM. 
NULL, 

uiSystemError, 

MAKELANGID(LANG_NEUTRAL, SUBLANG.NEUTRAL), 
szMessage, 

MAX_PATH, 

NULL); 

// display a message box with this error 

MessageBox(hWnd. szMessage, pszErrorCapti on. MB_0K | MBJCONSTOP); 
return; 

} // DisplaySystemMessage 
/* End of File */ 


released to developers, so that they could incorporate the 
same look and feel into their own applications. When a con¬ 
trol uses CTL3D, its text and background color changes. This 
note explains how to detect whether a control uses CTL3D 
(along with a code snippet), and why you need this informa¬ 
tion. ctl3dv2.dll wasalaterl6-bitversionandctl3d32.dll is 
the 32-bit version. For purposes of this discussion, I will refer 
to all of them as CTL3D. 

CTL3D changes some of the default behavior of a control 
with respect to text colors and background colors. The behav¬ 
ior of a control, therefore, depends on whether the control 


uses CTL3D or not. For example, a static control uses 
C0L0R_WINDOWTEXT for the text color and COLOR_WINDOW for the 
background color. (You can get the default colors using the 
function GetSysColor().) However, when the control uses 
CTL3D for 3D effects, it uses C0L0R_BTNTEXT as the text color 
and C0L0R_BTNFACE as the background color. Other controls are 
similarly affected. Thus, while coding default background col¬ 
ors for a control, you might want to know whether it uses 
CTL3D or not. 

CTL3D works by subclassing the existing controls to draw 
the 3D effects around them. Since it needs to store the original 
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window procedure, it stores it as a window property. You can 
store window-specific information as properties by supplying a 
property name (as a string) and the value to store (as a HANDLE). 
You use SetPropO to set a property and GetPropO to retrieve 
the property value. In 16-bit versions, CTL3D sets two proper¬ 
ties, namely C3dH and C3dL, while in 32-bit versions, it sets a sin¬ 
gle property, C3d. Consequently, if a control has a non-NULL 
value for these properties, it means that the control has been 
subclassed by CTL3D, and therefore uses it. The code fragment 
in Figure 1 describes a function. UsingCtl 3d ()(), which returns 
TRUE if the window uses CTL3D, FALSE otherwise. 



Handling Constructor 
Failure 


Tom Nelson 
Lansing, MI 


Many programmers seem to find con¬ 
structor failure an awkward situation to 
handle at times — if they don't simply 
ignore the problem entirely. The difficul¬ 
ty arises mainly from the fact that class 
constructors can't return a value that 
indicates valid object construction. 
Obviously, calling member functions on 
an invalid object (for example, if buffer 
space wasn't allocated correctly) may 
lead to program failure. There are sever¬ 
al ways to deal with this problem, most 
of them inelegant to various degrees. 
The worst way is to force every member 
function to assert whether or not its par¬ 
ent object is valid. 

Even though constructors can't 
return values like other member func¬ 
tions, there is a legal way to mimic this 
behavior. In ctorfail.cpp (Listing 2), I 
present a simple class that handles 
buffering for FILE-based streams. Class 
BufferedFi 1 e includes the logical nega¬ 
tion operator ! () configured to assert 
valid object construction. It returns 0 if 
construction proceeded normally, or 
non-zero if the object is not valid. This 
behavior makes it possible to use the 
returned object in conditional statements 
that test for failure using logical nega¬ 
tion, as if the constructor actually 
returned a value. 

The demo program, ctorfail.cpp 
(Listing 1), opens two BufferedFi le 
objects, one using an automatic object, 
the other dynamically. The demo asserts 
valid construction using i f (!...) blocks 
similar to the way you would test a nor¬ 
mal function return value for failure. 


Figure 1 


The UsingCtl3d() function 


#define CTL3D_PR0P1 "C3dH" 

^define CTL3D_PR0P2 "C3dL" 

#define CTL3D "C3d" 

BOOL UsingCtl3d (HWND hWnd) 

{ 

ASSERT (::IsWindow (hWnd)); 
fifdef WIN32 

if (GetProp (hWnd. CTL3D)) 

#else 

if (GetProp (hWnd, CTL3D_PR0P1) && GetProp 
(hWnd, CTL3D_PR0P2)) 

#endif 

return TRUE; 

else 

return FALSE; 

} 
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Listing 2 ctorfail.cpp 


/*. 

* Filename: 

* Summary: 

* Author: 

* Compiler: 

* Compile options: 

* Start date: 

* Last update: 

* Version: 

* 

★ _ 


ctorfail.cpp 

Demo: assert valid object 
T.W. Nelson 
BCC++ 4.0 

23 - Dec -1995 
23-Jan-1996 
1.00 


*/ 


#include <stdio.h> 

((include <stdlib.h> 

#include <new.h> 

class BufferedFi1e 
( 

private: 

FILE *_fp; 
char *_buf; 

int JsvalidO const //assert class invariant 
{ return ((_fp !- 0) 88 (_buf !- 0)); 

} //— 0 if object not valid 

public: 

BufferedFileO : _fp(0). _buf(0) {} //default 
BufferedFi1e( const char *name, 
const char * mode, 
size_t bufsz = 1024 ) 

{ new_handler oldh - set_new_handler(0); 

_buf - new char [bufsz]; //ignore bufsz — 0 
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Note that you must dereference a pointer to access the object 
it points to. If not, you will test only the contents of the point¬ 
er itself. 

If a dynamically allocated new object tests invalid, you 
should immediately delete it. (The compiler inserts calls to 
destructors for automatic objects.) It's tempting to write oper¬ 
ator ! () so that it handles object destruction itself (i.e., del ete 
thi s), but it's dangerous when you're working with automat¬ 
ic objects (see C/C++ Users Journal, August 1995, pg. 91). 

Buff eredFi 1 e includes two other overloaded operators, 
unary typecast intd and void *(). You can also configure 
either of these operators to assert valid construction. In this 
case, however, they must return 0 to indicate constructor fail¬ 
ure, the reverse of operator !(). While this method would 
probably serve for most situations, it may lead to operator 
ambiguities. 

For example, some mathematical classes (such as complex, 
rational, etc.) use typecast operators such as i nt( ) or doublet) 
in mixed-type computations. In ctorfail .cpp, operator into 
converts a Buf feredFi 1 e object to an int value. Although this 
conversion is meaningless for a class of this type, it shows one 
example of operator ambiguity. To demonstrate, see what 
happens when you comment out operator ! () and recompile. 
The compiler will then be unable to distinguish between oper¬ 
ator int() and void * () within the i f (1...) conditional state¬ 
ments. You can resolve the ambiguity by also removing oper¬ 
ator i nt() from compilation. The compiler then uses operator 
void *() for the conditional test. You can also rewrite i nt() to 
do essentially the same thing as void *0, except that it must 
return an i nt value. 

To summarize, any of the three operators discussed here 
can mimic constructors that appear to return a value. Both 
typecast operators can test for either constructor success or 
failure, but using them can result in conflicts if your class 
needs the same operators for other purposes. Using operator 
! () will probably lead to the fewest potential conflicts, but you 
can only use it to test for constructor failure. 



Create a Toolbar in Every MDI Child Window 


Mike E. Mikailov 
Columbia, MD 


Follow the steps described below to have a toolbar in every 
child window of an MDI Application created in the Visual 
C++ environment. 

1. Create an MDI Application (for example, TOOLBARS) by 
using App Wizard. 

2. Create a new MDI child window class (for example 
CNewChi 1 d). Derive it from CMDIChi 1 dWnd by using Class 
Wizard. 

3. For the new class, create an OnCreateO handler for the 
WM_CREATE message by using Class Wizard. You can cut and 
paste the following code from the mai nf rame.cpp file to the 
OnCreateO handler: 
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if (!m_wndToolBar.Create(this) I 

!m_wndToolBar.LoadToolBar(IDR_T00LBAR1)) 

{ 

TRACEOCFailed to create toolbar\n”); 
return -1; // fail to create 

} 

4. Create a toolbar bitmap resource with IDR_T00LBAR1 ID 
using AppStudio. This toolbar will appear in the child win¬ 
dows. 

5. Add the following public data member in the child class . h 
file: 

CToolBar m_wndToolBar; 

6. Include your new child class .h file into your project . cpp 
file (tool bars. cpp in the example provided on the WDJ code 
disk). 

7. In the toolbars.cpp file, use the newly derived child win¬ 
dow class to replace CMDIChi 1 dWnd in AddDocTemplateO, as 
shown below: 

AddDocTemplate ( new CMultiDocTemplate( 

IDR_T00LBATYPE, 

RUNTIME_CLASS(CTool barsDoc). 

// RUNTIME_CLASS(CChi1dFrame), // custom MDI child frame 
RUNTIME_CLASS(CNewChiId). // use this MDI child frame 
RUNTIME_CLASS(CToolbarsVi ew))); 

8. Build and run the application. You will see the toolbar in 
every child window. A complete application is provided on 
the code disk as toolbars.zip (see Table of Contents for 
availability). 


Listing 2 continued 


_fp - fopent name, mode ): 
if( JsvalidO ) 

setvbuf( Jp, _buf, _I0FBF, bufsz ); 
set_new_handler(oldh); 

1 

-BufferedFileO 
{ fclose(_fp); 
if( _buf ) 

delete _buf; 

1 

int operator ! 0 //returns !0 on failure 
{ return JsvalidO ? 0 : 1; 

1 

operator int 0 //demonstrates (int) typecast and 
{ return 5: //possible operator ambiguity 
1 

operator void * 0 //returns 0 on failure 

{ return (void *) (JsvalidO ? this : 0); 

1 

1 : 

int main( int argc, char **argv ) 

{ 

if (argc !- 3) 

exit(printf("Usage: %s infile outfile\n", argv[0])); 

BufferedFi1e inputt argv[l], "r", 2048 ); 

BufferedFile *output - 

new BufferedFile! argv[2], "w+". 2048 ); 

if( iinput ) //calls operator !() 

{ printfO'Can't open %s\n", argv[l] ): 
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Listing 2 continued 


// 'input' deleted automatically. 

return -1; 

} 

else if( !*output ) //calls operator !() 

{ printf("Can't create %s\n", argv[2] ); 
delete output; //explicit delete 
return -1; 

} 

printf( "Both files opened successful 1y\n" ); 

//. other program content . 

//This statement forces use of operator into for 
//type conversion. You must explicity cast 'input' 
//to an int value to resolve ambiguity with 
//operator void *0 . 

int b - 6 + int(input); //b — 11 
delete output; 

return 0; 

} 

/*.EOF . */ 


There is also an opportunity to have a different toolbar for 
each new document type instead of for every child window. In 
this case, replace the main toolbar with an appropriate differ¬ 
ent toolbar (created using AppStudio) in the corresponding 
child frame. I assume that for a new type of document you 
would have a corresponding main menu resource linked with 
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the document, its view, and the child frame via 
AddDocTemplateO. For example, in toolbar. cpp's OnCreateO 
handler, instead of using the this pointer, use the pointer to 
the main frame window object returned by GetMD I Frame () to 
replace the toolbar: 

CMainFrame* pFrameWnd =(CMainFrame*)GetMDIFrame 0 ; 

if (!pFrameWnd -> m_wndToolBar.LoadToolBar(IDR_T00LBAR1)) 

{ 

TRACEOC’Failed to replace toolbar\n"); 
return -1; // fail to create 

} 


Make m_wndToolBar public in the CMainFrame class definition 
and optionally uncomment the following lines if you are 
using Visual C++ 4.0: 

/* 

// TODO: Remove this if you don’t want tool tips or a 
// resizeable toolbar 

m_wndToolBa r.SetBa rSty1e(m_wndToolBa r.GetBa rStyle() 

CBRS_T00LTIPS I CBRS_FLYBY 
CBRS_SIZE_DYNAMIC); 

// TODO: Delete these three lines if you don’t want the 

// toolbar to be dockable 

m_wndToolBar.EnableDocking(CBRS_ALIGN_ANY); 

EnableDockingC CBRS_ALIGN_ANY); 

DockControlBar(&m_wndToolBar); 

*/ 

The Microsoft Developer Network CD contains a similar arti¬ 
cle, "How to Create a Status Bar in Every MDI Child Window" 
(PSS ID Number: Q121946). □ 
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TCP and SMTP for Windows 

Victor R. Volkman 


Introduction 

TCP for Windows, by Philippe Jounin of the SNCF (French 
Railways), is a DLL that provides a simpler interface for com¬ 
municating via the Internet Transmission Control Protocol 
(TCP). TCP is a connection-oriented, bidirectional data stream 
service. The Internet applications that you use every day (ftp, 
gopher, telnet) all make use of TCP connections. TCP for 
Windows (hereafter, TCP4W) supports TCP communication 
in general and also has specific functions for handling the 
Telnet protocol. TCP4W is not a replacement for Windows 
Sockets; rather, it is a higher-level layer that provides simple 
entry points for sophisticated TCP transactions that use sock¬ 
ets (see Figure 1). Using tcp4w.dll, you can build a basic 
Telnet client in about 200 lines of code. TCP4W will work 
with most language systems capable of calling DLLs, includ¬ 
ing C, C++, and Pascal for Windows. TCP4W includes a 16- 
bit DLL for Windows 3.1 and a 32-bit DLL for Windows 95 
and NT. Before diving into the entry points. I'll review some 
specifics of Telnet first. 

About Telnet 

Telnet is an officially recognized TCP/IP stan¬ 
dard protocol for remote terminal connection 
service. Telnet allows a user on one machine to 
establish a TCP connection to a login server at 
another. Having done so, it then passes key¬ 
strokes from the user's terminal directly to the 
remote machine, as if they had been typed on a 
terminal wired into the remote machine. To make 
the illusion complete, it also carries output from 
the remote machine back to the user's terminal. 

Telnet provides a network virtual terminal, 
allows negotiation of standard options, and 
treats connections symmetrically. Providing a 
"network virtual terminal" means that there is a 
standard interface to remote systems. If you 
implement the Telnet protocol properly once, 
then you need not change it regardless of what 
types of hosts you connect to. Feature negotiation 
through DO/DON'T and WILL/WON'T com¬ 


mands handles inherent differences. A telnet session doesn't 
require the client side to physically be a terminal. Thus, an 
arbitrary program can take the place of a real terminal. 

Though Telnet lacks features found in more complex pro¬ 
tocols, it still remains the most widely implemented remote 
connection protocol in the world. For more information on 
Telnet, read Internet RFC 854 (see the sidebar, "How to Get 
the Windows Sockets and Telnet Specifications," for informa¬ 
tion on how to obtain the RFC). As you can see, telnet — and 
related TCP protocols — are more than just a pair of Windows 
sockets. 

TCP4W API Overview 

You must call Tcp4wlnit() before you can call any other 
function in the API. This function allocates buffers and also 
stores information about the invoking task. Along the way, 
Tcp4w I n i t () calls the Windows Sockets API (WSA) function 



Product: TCP for Windows (TCP4W), vl.2 

Filename: TCP4W12.ZIP 

Address: Philippe Jounin 

58 Rue Corvisart 
75.013 Paris 
FRANCE 
ASP Member: No 

Email: Internet: ark@ifh.sncf.fr 

FTP: papa.indstate.edu(139.102.70.202):/winsock-1/packages 

Registration: freeware (see text) 

Evaluation: N/A 

Source Code: N/A 

Alternately, you can download TCP4W12.ZIP from the following BBS: 
HAL 9000 BBS: +1 313 663 4173 or telnet HAL9K.COM. 


Victor R. Volkman received a BS in Computer Science from Michigan Technological University. He has been a contributing editor to 
Windows Developer's Journal Since 1990. He is currently employed as a senior analyst at H.C.I.A of Ann Arbor, Michigan. He can be 
reached at the HAL 9000BBS (313) 663-4173, URL http://xvzmv.HAL9K.com/, or email to sysop@HAL9K.com. 









How to Get the Windows Sockets and Telnet Specifications 


You can get the specifications and support files by anony¬ 
mous FTP from ftp.ftp.com:/support/ftpsoft/winsock. 
Here is a list of files you'll want to have: 


WS_TXT.ZIP 

77837 

Windows Sockets Spec 1.1 in .txt 
file 

WS_DOC.EXE 

112064 

Windows Sockets Spec 1.1 in 
WinWord format 

WS_FAQ.ZIP 

5787 

Windows Sockets Frequently 
Asked Questions 

WS_H.ZIP 

8301 

WINSOCK.H header file (required 
for compiling) 

WS_HELP.ZIP 

156971 

WINSOCK.HLP as MS Windows 
HELP file 

WSJNC.ZIP 

3235 

WINSOCK.INC file (required for 
compiling) 

WS_DEF.ZIP 

1238 

WINSOCK.DEF module definitions 


Alternately, you can download all these files from: 

BBS HAL 9000 BBS: +1 313 663 4173 or telnet hal9k.com 

The Telnet protocol exists as an adopted Internet standard in 
Internet RFC (Request For Comment) #854. You can get RFC 
854 by anonymous FTP from: 

ds. internic.net:/rfc/rfc854.txt 

or download rfc854.txt from the HAL 9000 BBS (listed 
above). □ 


WSASta rtup (), if necessary. 

After the initial setup, applications generally fall into the 
behavioral model of either client or server. In either case, your 
next step is to open a connection. A client application would 
call TcpConnect () and a server application would call 
TcpGetListenSocketf ), followed by TcpAcceptO. When the 


connection is open, you can retrieve the fully qualified 
Internet domain name (e.g., "hal9k.com") or IP address (e.g., 
152.160.13.1) of machines at either end of the socket. 

The following sample application will try to establish a 
Telnet connection with hal9k.com. It waits for its answer, then 
closes the connection and terminates. 
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/ 
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#1nclude <windows.h> 

^include <tcp4w.h> 

int PASCAL WinMain (HANDLE hlnstance, 

HANDLE hPrevInstance, 

LPSTR IpszCmdLine. int nOndShow) 

{ 

char szStr [256]; 
char szReply [100]; 

SOCKET CSock; 
int Rc; 
short nPort-0; 

if (Tcp4wlnit 0 !- IP.SUCCESS) return 0; 

Rc - TcpConnect (& CSock, “hal9k.com", “ftp", & nPort); 
if (Rc—IP_SUCCESS) 

{ 

TcpRecv (CSock, szReply, sizeof szReply-1, 

60. HFILE.ERROR); 

TcpClose (& CSock); 
wsprintf (szStr, 

f'Connection successful on port 
%d\nserver said:\n\n%s", 
nPort, (LPSTR) szReply); 

1 

else 

wsprintf (szStr, "Connection failed\nerror %d". Rc); 
MessageBox (NULL. szStr, "Test Tcp4w", MB_0K); 

Tcp4wCleanup 0; 
return 0; 

} 


After getting connected, your applica¬ 
tion can send or receive data with func¬ 
tions such as TcpSendO or TcpRecvO. 
When using a telnet-based protocol, 
you would instead call TnSendO, 
TnReadLine( ), or TnGetAnswerCodet ). I'll 
explain more on variations of these 
functions in the next section. 

Before shutdown, your application 
must call TcpCl osel ) for each opened 
socket and then T cp4wC 1 eanupf ) to 
cleanly free all resources. 

Sending and Receiving 

TCP4W provides many functions 
related to the transmission of data (see 
Figure 2). Before comparing and con¬ 
trasting them. I'll point out a few things 
the API functions have in common. All 
API functions return only when the 
associated operation is finished or if a 
timeout has occurred. This means they 
may be considered "blocking" calls with 
respect to applications. While a process 
is waiting for a blocking call, it may still 
receive Windows messages (e.g., 
WM_TIMER), and might potentially try 
to call another network function. TCP 
for Windows will detect this second call 
and return a failure message to avoid 
reentrance. To cancel a blocking call, the 
application should call TcpAbortO or 
WSACancel B1 ockingCal 1 () and then 
return control to Windows. 

If you want to avoid the blocking 
issue altogether, you can call 
TcpIsDataAvai 1() or 

TcpIsOOBDataAvai 1 () with the socket 
that you wish to inquire about. These 


functions return TRUE if normal data or Out Of Band (OOB) 
data is currently ready for reading. This means your applica¬ 
tion can go ahead and do other processing and try again later. 
In some scenarios, you may still prefer the blocking metaphor. 

As mentioned earlier, to accommodate the formats expect¬ 
ed by TCP services from archie to veronica, TCP4W provides 
several methods of sending and receiving data. Though all of 
these services use the same underlying TCP transport, each 
individual service has its own data formats and protocols (as 
documented by their respective RFCs). 

You can send data with the TcpSendO, TcpPPSendO, or 
TnSendO API calls. The choice of which function to use 
depends on the details of the service you're talking with. 
TcpSendO and TcpPPSendO use the same calling sequence: 





for C/C++ 
-lint Version 7.0 (New) 

presents Bug # 661 


for( i = 0; i <= 10; i-i 
a[i] = 0; 
return 0; 

> 


This program is supposed to clear an array and then return; but it has a slight 
problem. Can you spot it? Call if you need a hint. Refer to Bug #661. 


PC-lint for C/C++ will catch this and many 
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Microsoft C/C++. 
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socket, buffer, length of buffer, priority, and logfile. 
TcpPPSendO prepends a two-byte word indicating the packet 
length ahead of the packet. TnSendO, for telnet connections, 
sends a single null-terminated string and appends the CR/LF 
pair for you. Each of these three functions allows for sending 
high priority Out Of Band (OOB) data (see Comer[l] for a 
description of OOB usage). The optional logfile parameter 
saves a copy of incoming data to a logfile for later debugging 
and analysis. 

As you might expect, TCP4W offers a complementary set 
of functions for receiving data: TcpRecvO, TcpPPRecvO, 
TcpRecvUntilStrO, TnReadLineO, and TnGetAnswerCode(). 
These functions have a similar calling sequence: socket, buffer. 


length of buffer, timeout, and logfile. The timeout value tells 
how many seconds to wait for transmission. A timeout condi¬ 
tion indicates either that the host on the other side of the con¬ 
nection has not sent its data in time or that the network has 
gone down. TcpRecvUntilStrO accommodates a variable- 
length transmission terminated by a user-defined string of 
bytes. Though this could encompass several individually 
received packets, they must all fit within the size of the receive 
buffer that you supply. 

TnReadLineO and TnGetAnswerCodeO provide two different 
ways to read from a Telnet connection. TnReadLineO simply 
reads all incoming characters up to the next EOL character (line¬ 
feed). TnGetAnswerCode( ) parses the full Telnet line for command 
codes. A command code is a number between 100 and 999 that 
appears after an LAC (Interpret As Command) 
escape character. Again, your choice of receive 
commands depends largely on the underlying 
details of the service you're accessing. 

Other Libraries of Interest 

If you're interested in developing applica¬ 
tions that use Internet FTP or SMTP client 
functionality, then you'll also want to check 
out Jounin's FTP for Windows and SMTP 
(Simple Mail Transport Protocol) for 
Windows libraries. For a description of FTP 
for Windows (FTP4W), see the Shareware 
Spotlight column in the May 1995 issue of 
Windows Developer's Journal. Both FTP4W and 
SMTP4W can be found in the same place as 
TCP4W (see product information box). 

Documentation, Licensing, and 
Support 

TCP4W includes a 22-page "TCP4W API 
User Manual" in Windows Write (,wri) for¬ 
mat. The manual provides a brief overview of 
the underlying structure of TCP applications. 
The remainder of the manual supplies a 
detailed reference for each API function 
including syntax, return values, and code 
fragments showing intended use. Minor flaw: 
some of the simpler functions, such as 
TcpIsDataAvail (), have no entries in the man¬ 
ual. 

TCP4W was written with the help of 
Andreas Tikart, who also wrote the Pascal 
samples. The package comes with the full 
Pascal source and executables for three com¬ 
plete TCP applications: Line Printer Queue 
(lpq), Telnet client, and Koala client. The doc¬ 
umentation and examples should be suffi¬ 
cient to get you started on your way, even if 
you have no previous experience with 
Windows Sockets. 

Jounin distributes TCP4W as a freeware 
package. Fie grants permission without 
restriction to use and distribute TCP for 
Windows under the following conditions: 


Figure 2 TCP4W API Listing 


int Tcp4wlnit (void): 
int Tcp4wCleanup (void); 
int TcpAbort (void); 

int TcpAccept (SOCKET far *pCSock, SOCKET ListenSock, UI NT nTO); 

int TcpConnect (SOCKET far *pS, LPSTR szServer. LPSTR szService, 
short far *1pPort); 

int TcpClose (SOCKET far *p$); 

int TcpFlush (SOCKET s); 

int TcpGetListenSocket (SOCKET far *pS, LPSTR szService, 
short far *1pPort. int nPendingConnection); 

int TcpRecv (SOCKET s, LPSTR szBuf, unsigned uBufSize, 
unsigned uTimeOut, HFILE hf); 

int TcpSend (SOCKET s, LPSTR szBuf, unsigned uBufSize, 

BOOL bHighPriority, HFILE hf); 

int TcpGetLocalID (LPSTR szStrName, int uNameSize, 

DWORD far *lpAddress); 

int TcpGetRemotelD (SOCKET s, LPSTR szStrName, int uNameSize, 

DWORD far *1pAddress); 

BOOL TcpIsDataAvail (SOCKET s); 

BOOL TcpIsOOBDataAvail (SOCKET s); 

int TcpPPRecv (SOCKET s, LPSTR szBuf, unsigned uBufSize, 
unsigned uTimeOut, BOOL bExact, HFILE hLogFile); 

int TcpPPSend (SOCKET s, LPSTR szBuf, unsigned uBufSize, 

HFILE hLogFile); 

int TcpRecvUntilStr (SOCKET s, LPSTR szBuf.unsigned far *1pBufSize, 

LPSTR szStop, unsigned uStopSize, BOOL bCaseSensitive, 
unsigned uTimeOut, HFILE hLogFile); 

int TnReadLine (SOCKET s, LPSTR szBuf, UINT BufSize, UINT uTimeOut, 

HFILE hf); 

int TnSend (SOCKET s, LPSTR szString, BOOL bHighPriority, HFILE hf); 

int TnGetAnswerCode(SOCKET ctrl_skt,LPSTR szInBuf,UINT uBufSize, 

UINT uTimeOut, HFILE hf); 


* All functions declared "far pascal" 
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• TCP4W is distributed without charge 

• TCP4W is not modified in any way 
•Distribution of tcp4w.dll must be 

accompanied by tcp4w.wri 
Jounin further stipulates that TCP4W 
may be included on CD-ROMs or other 
distribution methods freely, provided 
any charge for such is for recovering the 
cost of distribution and reasonable prof¬ 
it and not for the purpose of "selling" it. 

Since TCP4W is freeware, technical 
support for its use is necessarily limited. 

From past experience, I know that 
Jounin is very interested in hearing com¬ 
ments via email and often accommo¬ 
dates useful suggestions to improve 
functionality. [Note: This article describes 
vl.2. Now available is vl.5, which includes 
both 16-bit and 32-bit DLLs. Philippe Jounin 
says that since vl.5 provides few new func¬ 
tions, you should be able to use it in place of 
vl.2 with no risk.] 

References 

[1] Comer, Douglas E. Internetworking with TCP/IP — Volume I: 
Principles, Protocols, and Architectures. 2nd ed. Englewood 
Cliffs, N.J.: Prentice Hall, 1991. Chapter 22. 

An authoritative reference on the internals of TCP/IP, 
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“OUR ACCOUNTING PACKAGE DELIVERS A 
POWERFUL SQL DATABASE, AT A PRICE 
THE MIDDLE MARKET CAN AFFORD” 

Brian Clark. Senior Vice President and General Manager. 
Solomon Software 


BRIAN: “Small to mid-sized businesses see 
their accounting systems as critical. Our cus¬ 
tomers focus on accounting, not database 
administration. They need accounting soft¬ 
ware that’s easy to use, maintenance free and 
has the full power of a relational database.” 


CHOICE 


VERN: “With Scalable SQL, our system 
delivers superior performance and flawless 
data integrity. We can support any customer 
environment, from mobile systems to full 
client/server-and customers are less affected 
by network traffic and system overhead.” 



BRIAN: "Scalable SQL gives users instanta¬ 
neous access to information. It provides all 
the advantages of database products costing 
three times as much. And it uses a fraction 
of the computing resources.” 


VERN: “When we set out to design Solomon 
IV, we envisioned a mission critical applica¬ 
tion for the middle market budget-an 
affordable product with an industry proven 
database, total data security and scalability. 
Scalable SQL made it all possible.” 


the complete story about Solomon IV, winner 
of the PC Magazine/Price Waterhouse award for 
best Windows®accounting software, contact BTI. 
http://www.btrieve.com • info@btrvtech.com 

SSSE5T. W BTRIEVE 

I I ■■ TECHNOLOGIES 



FOR SCALABILITY, PERFORMANCE AND 
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LIKE SCALABLE SQL” 
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Bug++ of the Month 

Mark Nelson 


I use multiple compilers from four different vendors on a 
daily basis at Greenleaf Software. This means I usually have at 
least a half-dozen or so compilers installed on my system at 
any one time. Each and every one of these compilers comes 
with optimization options that purport to keep you on the cut¬ 
ting edge of performance. 

Of course, regular readers of this column know that being 
on the cutting edge frequently mandates a trip to the C++ 
emergency room for stitches and butterfly bandages. (We refer 
to them as "patches," but we all know they cover ugly 
wounds, at least in our pride.) 

To Optimize or Not 

Optimizers are a source of great pride for compiler writers, 
but the hoi polloi of common coders don't universally embrace 
this technology. In fact, whether to use optimization or not 
seems to be a source of great debate. 

One reason the debate rages on is that there aren't many 
facts to work with. Competitive analyses of C++ compilers 
these days tend to concentrate on IDEs, application frame¬ 
works, and MFC support. In the old days of C technology, 
magazines like Computer Language and Programmer's Journal 
could be counted on to print densely packed tables full of exe¬ 
cutable size and space analyses. Graybeards like me would 
spend hours poring over the results like Talmudic scholars, 
looking for hidden strengths and weaknesses. Those days are 
no more. 

Instead, these days we fight the good fight with anecdotes. 
My favorite pro-optimization argument seems to pop up on¬ 
line every six months or so. It usally goes something like this: 

So-and-so took a look at the generated code for compiler X 
with full optimization. This guy knows more about bit-twid¬ 
dling than anyone I know, and he said the compiler was final¬ 
ly generating code as good or as better than he could do by 
hand. 


Sounds pretty good, right? But the counter argument is per¬ 
suasive as well: 

Joe Blow at <big-corporation> told me that they build their 
final product with optimization turned off everywhere. Seems 
that every time they enable optimization, support calls go 
through the roof. 

This Month's Anecdote 

There is no doubt about one thing: optimizers do have 
bugs. This month's bug was spotted by reader Dave 
Sharpless. Unhappy with the way Borland C++ 4.5 was gen¬ 
erating his code, Dave was performing the programming 
equivalent of a random blow with a handy hammer — that is, 
he was trying out various combinations of optimization 
switches to find something that worked. 

In the process, Dave exposed a really horrible bug by using 
just the wrong switch. Dave compiled the following code frag¬ 
ment using loop optimization only: 

char array[10]; 

void main() 

{ 

for ( int i = 0 ; i < 10 ; i++ ) 
array[ i ] = 5; 

} 

In this case, the optimizer decided that it didn't need a stack 
frame, since it could keep the single local variable in a register. 
Unfortunately, when it exits the loop, it generates the follow¬ 
ing piece of code: 

mov word ptr [bp],10 

Since it never allocated any variables on the stack, this code ran¬ 
domly wipes out a word belonging to someone else, leading to 


Mark Nelson is a programmer for Greenleaf Software in Dallas, Texas. Mark is the author of The C++ Programmer's Guide to the 
Standard Template Library, from IDG Books, as well as The Data Compression Book, from M&T Books. You can reach Mark on 
the Web at http://web2.airmail.net/markn. 
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WM_GETDLGCODE Quicklnfo Overview Group 


WM GETDLGCODE 


The WM_GETDLGCODE message is sent to the dialog box 
procedure associated with a control. Normally, Windows handles all 
arrow-key and TAB-key input to the control. By responding to the 
WM_GETDLGCODE message, an application can take control of a 
particular type of input and process the input itself. 


Annotate 


Cunent annotation 


The documentation WM_GETDLGCODE states that this 
message has no parameters. But the truth is that if the user 
presses a key, IParam will contain a pointer to a MSG 
structure containing information about the event that made 
Windows send the WM_GETDLGCODE message. This is 
indirectly documented in windowsx.h. where the 
HANDLE_WM_GETDLGCODE0 macro passes two 
arguments to the handler: the window handle and (MSG 
FAR*) (IParam). 

Submitted by: Patrick Tennberg 


who-knows-what. And for the final indignity, Dave was unable to 
convince Borland of the righteousness of his bug report! 

WDJ Picks up the Ball 

After fiddling with Dave's bug for a while, I came up with 
the demonstration program shown in bug0496 . cpp (Listing 1). 
It was a bit of a challenge to demonstrate the bug with a pro¬ 
gram that still managed to exit with any dignity whatsoever, 
so I'm happy with the final result. 

The bug Dave found shows up in routine f 00 (). To demon¬ 
strate it, main() has enough local data to generate a stack 
frame. When f oo () is called, the stack contains all of the local 
variables from mai n(), plus a saved copy of BP, plus the return 
address. As it happens, the saved value of BP is wiped out. 

I demonstrate that BP is trashed by using Borland's pseudo¬ 
register to pick up the register's value before and after foot) 
is called. The output looks like this: 

a = 1 [should be 1] 
b = 2 [should be 2] 
c = 29295 [should be 3] 
bp = 64 [should be -10] 

Abnormal program termination 

Variables a and b come through unscathed, as they are stored 
in registers. Variable C is on the stack frame, so it is lost when 
the value of bp is mangled. All in all, a very nasty situation. 

Vendor Response — Your Response? 

Brian Myers of Borland was quick to own up to the bug, and 
reported that it has been fixed in the codebase for Borland's 




Introducing Track Record 2.0, a new kind of 
tool from the original developers of BRIEF 


Take control 
of your software 
projects! 


Developing software means juggling 
hundreds of details. Let just one of 
them fall through the cracks, and 
you're in for headaches. Wouldn't it 
be great if you had a tool that let you 
take control of all that information? 

Now you do. Track Record® 
is the first and only application 
designed to help you keep track of 
practically everything relating to your 
work — from bugs to beta sites. It's a 
whole new kind of productivity tool 
for Microsoft Windows, designed 
specifically for software developers. 


• Track Record lets you quickly and 
easily plan tasks, store and retrieve 
information and keep a detailed 
history of who did what, when. 

• Track Record dynamically displays 
information about your software pro¬ 
jects as they change, so you're always 
up-to-date. 
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out of the box, or configure it to meet 
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entire workgroup on track! 


Track Record is a registered trademark of UnderWare, Inc. BRIEF is a registered trademark of Borland International. 
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"If you’re a software developer whose 
system for tracking bugs and scheduling 
appointments is to scribble them on scraps 
of paper, then Track Record is for you." 

— Richard Hale Shaw, PC Magazine, January 11,1994 

"Track Record is clearly the technology 
leader — the most flexible and sophisticat¬ 
ed of the bug trackers." 

— Dave Duchesneau, Data-Based Advisor, June 1995 

"Track Record, from UnderWare, 
whose authors wrote BRIEF, is one of the 
most impressive pieces of software I've 
ever used." 

— Tom Swan, PC Techniques, April/May 1994 
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Listing 1 bug0496.cpp — Demonstrating a Borland C++ loop optimization bug 


// 

// BUG0496.CPP 
II 

II This program demonstrates a code generation bug in 
// the 16 bit version of BCC 4.5x. When compiled with 
// the following command line: 

II 

// bcc -01 bug0496.cpp 
II 

// food mistakenly writes the value 64 
// to the stack, even though i is a register 
// based variable. Writing out a value to 
// a random location on the stack is a bad 
// thing. In this case, it wipes out the stored 
// bp from the calling routine. The main 
// routine detects this error, prints it 
// out, and attempts to deal with it by 
// calling the abortO function. 

// 

#include <iostream.h> 

//include <stdlib.h> 


char array/ 64 ]; 


void food 
{ 

fort int i - 0 ; i < 64 ; i++ ) 
array/ i ] - 6; 

} 

maind 

{ 

int a - 1; 
int b - 2; 
int c - 3; 

static int good_bp - _BP; 
food: 

cout « "a = " « a « " (should be l)\n" 

cout « "b - " << b « " (should be 2)\n" 

cout « "c = " « c « " (should be 3)\n" 

cout « "bp - " « _BP « " (should be " 

« good_bp « ")\n"; 
abortd: 

return a + b + c; 


//End of file 


next release. Let's hope we've seen the last of this one! 

After reading Dave's email, there was no doubt in my 
mind regarding how he felt about Borland's optimization. But 
I'd like to hear your opinion as well. Do you use optimization? 
Do you trust it? Does your company have a policy regarding 
its use? I'll try to summarize your responses in a future issue. 


Of course, Dave will be sporting a handsome new WDJ 
tee-shirt as our way of saying thanks. Is your C++ bug report 
ready for prime time? If you think it might be, send it to 
wdl etter@rdpub.com, and you just might join the purple-clad 
legion! O 
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Multithreaded Programming 
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A number of articles and books describe threads and the 
syntax of the Win32 synchronization objects. Some of these 
sources even do a good job of explaining how to solve basic 
synchronization issues such as the old multiple-readers-sin- 
gle-writer problem. What often seems to be missing is back¬ 
ground information on why you would want to use multiple 
threads in the first place. A single-threaded application is 
much easier to write and test, so why use a multithreaded 
implementation? In reality, not all applications benefit from 
multiple threads. Trying to force a multithreaded design on a 
fundamentally sequential task may just result in threads that 
spend most of their time waiting on each other and on context 
switches between threads. This column discusses some issues 
that can help you create intelligent uses for multithreading, 
especially in the multiprocessor environment that Windows 
NT supports. 

Introduction 

There are two conditions that make an application a good 
candidate for a multithread design. First, if there's a point 
where the application is waiting for some resource or data 
(such as waiting for disk I/O to complete), then there's an 
opportunity for doing other useful work during that wait. 
Second, multiple threads allow applications to take advantage 
of multiprocessor systems. So, to oversimplify somewhat, 
there are really two forms of multiprocessing. The simple 
form can be performed on almost any single-processor system 
by requesting asynchronous I/O operations to devices, such 
as the hard disk. This allows the CPU to go on executing code 
while the device's controller is handling the I/O request. 
Asynchronous I/O is a powerful feature of Windows NT (but, 
unfortunately, not of Windows 95), and I will discuss this in 
more detail in next month's column. 

Some of the early attempts to make operating systems take 


advantage of multiple processors were less than optimal. For 
example, one of the easier ways to adapt UNIX to multiple 
processor systems was to reserve one processor for use when 
executing kernel code. This had the advantage of requiring 
relatively fewer changes to the operating system, but the dis¬ 
advantage was that the operating system could become a bot¬ 
tleneck, keeping other processors idle when more than one 
process needed the operating system to perform a request. NT 
implements a more general form of multiprocessor support, 
called symmetric multiprocessing (SMP); NT can run both 
operating system threads and user-mode threads on any and 
all available processors. Note that Windows 95 does not take 
advantage of multiple processors. While SMP systems have 
been fairly exotic in the past, the new Pentium Pro processor 
(code named the P6) provides much better inherent support 
for multiprocessing (up to four processors) than the previous 
generation Pentium processor. 

So what's the catch? To achieve good scaling on SMP 
machines requires careful design on the part of systems ven¬ 
dors, the operating system vendor, and the application ven¬ 
dors. There's a relationship (known as Amdahl's Law) that 
describes the predicted scalabilty of multiple processor sys¬ 
tems. Basically, it states that there is a severe diminishing 
return in SMP systems based on contention over shared 
devices and resources. In general, you can only expect to 
receive a 60 percent increase in performance with each added 
processor. By carefully eliminating other system bottlenecks 
(such as designs that implement shared caches, or slow I/O 
devices), as well as running well-designed multithreaded 
applications, you can conceivably approach a figure of closer 
to 80 percent scalabilty. Starting with a theoretical perfor¬ 
mance of 100, Table 1 lists the performance improvement (at 
both the 60 percent and 80 percent scaling factors) of adding 
processors to a system. 


Paula Tomlinson has been developing DOS, Windows and Windows-NT based applications and device drivers for eight years. The opin¬ 
ions expressed here are hers alone. She can be contacted via the internet at paulat@microsoft.com. 
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x(n+l) = (X(n) - X(n-l)) * ScalingFactor + X(n) 

As developers, our job is to design efficient multithreaded 
programs that minimize resource contention and thus take 
maximum advantage of all available processors. 

Windows NT Thread Scheduling 

To design efficient multithreaded programs, it's important 
to understand how the Windows NT scheduler works. The 
thread is the basic unit of execution and every process has at 
least one thread that is created implicitly by the runtime start¬ 
up code. WinMainO (or mainO) is executed in the context of 
that thread. The process is of course free to create as many 
other threads as it wants to within the limits of system 
resources. Threads are what the NT kernel (as well as 
Windows 95) schedules for execution on the processor (or 
processors). 

Both Windows NT and Windows 95 use a priority-based, 
time-sliced, preemptive multitasking algorithm for schedul¬ 
ing threads. Priorities are used to determine the order in 


which threads run. Higher priority threads are always sched¬ 
uled first, while threads with equal priority values are sched¬ 
uled in a round-robin fashion. A thread's effective priority 
value is based on a formula involving the process's base pri¬ 
ority value and a relative priority value associated with the 
thread. That formula ultimately produces a number between 
0 and 31, which is the thread's priority. (You may want to refer 
to Figure 1 as you read this discussion of thread priorities.) 

A process can have one of the following base priority val¬ 
ues: 

IDLE_PRIORITY_C LASS 
NORMAL_PRIORITY_CLASS 
HIGH_PRIORITY_CLASS 
REALTIME_PRIORITY_CLASS 

The first three classes are referred to as the dynamic priority 
classes and are commonly used by user-mode processes. 
Although a process can assign itself the real-time priority 
class, that class is generally reserved for critical system 
threads. The process base priority sets the base level for all 


Figure 1 Priority levels 
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threads within that process. The code that spawns the process 
controls the process's starting base priority, but the process 
itself sets the priority of any threads it spawns, though the 
thread priority is relative to the process base priority (see 
Figure 1). 

A thread can have one of the following relative priority val¬ 
ues: 

THREAD_PRIORITY_LOWEST 

THREAD_PRIORITY_BELOW_NORMAL 

THREAD_PRIORITY_NORMAL 

THREAD_PRIORITY_ABOVE_NORMAL 

THREAD_PRIORITY_HIGHEST 

THREAD_PRIORITY_IDLE 

THREAD_PRIORITY_TIME_CRITICAL 

As Figure 1 shows, the first five relative thread priority values 
allow the overall thread priority to vary two levels above or 
below the base priority class of the process. In other words, 
starting a thread with priority THREAD_PRIORITY_HIGHEST really 
means "assign this thread a priority two higher than the base 
priority of this process." Flowever, the time-critical 
(THREAD_PRIORITY_TIME_CRITICAL) and idle 

(THREAD_PRIORITY_IDLE) relative thread priorities behave a lit¬ 
tle differently. 

As shown in Figure 1, if the current process has the base 
priority class of RE A L_T IM E_P R10 RI TY_C LASS, then a time-critical 
thread priority means a priority of 31, and an idle thread pri¬ 
ority means a priority of 16. For all other base priority classes, 
giving a thread time-critical priority results in a priority of 15, 
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while giving a thread idle priority gives it a priority of 1. In 
other words, the top 16 priorities are the domain of real-time 
processes, while all the other classes of processes use priority 
ranges from the bottom 16 priorities. 

The system can also boost or reduce the priority class of a 
process based on whether it is running in the foreground or in 
the background. Foreground applications get a priority boost 
so that they can execute faster and thus be available to 
respond to user input. Other events, such as completion of an 
1/O operation, can also result in a temporary priority boost. 

In the old nonpreemptive multitasking days of 16-bit 
Windows, the applications essentially got to define their own 
time slice — with sometimes annoying and sometimes devas¬ 
tating results. Both Windows NT and Windows 95 are pre¬ 
emptively multitasked operating systems (though Windows 
95 cannot always smoothly multitask 16-bit Windows appli¬ 
cations) with fixed time slices (also called a time quantum). 
You shouldn't rely on or attempt to tune your applications to 
an exact value for the time slice, as that value varies between 
platforms and may vary between versions of NT (it currently 
ranges from 15 to 30 msec). Because it is a preemptive operat¬ 
ing system, you cannot guarantee that a user mode thread will 
keep running without loss of control for any specific period of 
time. Even a thread running at the highest possible priority 
will eventually use up its time slice and have to surrender to 
any other threads running at the same priority. 

Context Switches 

A given thread can be in one of six different states, but for 
my purposes, I will focus on how a thread enters and leaves 
the running state. To be runnable, a thread must not be wait¬ 
ing on any resource to become available (such as waiting to 
enter a critical section, or waiting for an event to be signaled). 
Once the thread is ready (runnable), it then waits until the 
scheduler picks it for execution. For the thread to be picked 
next to run, three conditions must be met. First, no thread with 
a higher priority can be waiting. Second, if there are other 
threads with equal priority, this thread must be the next one in 
line (remember that threads of equal priority are scheduled in 
a round-robin fashion). And, finally, there must be a processor 
available for the thread to run on. This brings me to the con¬ 
ditions by which a thread stops running (and frees up the 
processor for the next thread). 

A thread can stop running for one of four basic reasons. 
First, the thread can simply terminate (either voluntarily or 
involuntarily). Second, the thread can block (by waiting for 
something). Third, the thread can be suspended (from a call to 
SuspendThread ()). Fourth, the thread can be preempted either 
because its time slice expired or because a higher priority 
thread has become available (in which case the thread is 
immediately preempted, even before it finishes its time slice). 

Multithreading Strategies 

Ideally, the threads in your application will get scheduled 
often enough to get their work done, and they will not be 
fighting over scarce resources, which would incur the over¬ 
head of many context switches. The two aspects of context 
switching that the application can control most effectively are 
the priorities of its threads and how long the threads spend 
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waiting. You may be tempted to elevate your process to the 
real-time class and give all your threads the highest relative 
priority. I would not recommend this approach. First, high pri¬ 
ority threads will block if they need to wait for a resource, just 
like normal priority threads do. Second, threads running at 
real-time priority can severely affect the operating system's 
ability to take care of it's own housekeeping (such as cache 
flushing and mouse operation). Even having too many 
threads at the dynamic high priority class can affect things like 
the Task Manager's (which also runs at high priority) ability 
to kill errant processes. Use elevated thread priorities with 
caution, and remember the high priority values don't make up 
for poor thread design. Your first task should be to divide 
work into threads in such a way that the incidence of depen¬ 
dencies on shared resources is minimized and the amount of 
work that can be done in parallel is maximized. Only after that 
task is done should you consider assigning higher priority to 
a few key threads, if necessary. 

That still leaves the problem of thread-waiting to consider. 
It is generally not practical to avoid waiting at all costs. And, 
of course, one of the points of a multithreaded design is to 
allow other threads to run when the current thread is waiting 
on some resource. The trick is to do as much useful work as 
you can in between these waits, so that the system doesn't 
have to spend an inordinately large amount of time switching 
between threads. You also need to be aware of the ways your 
thread can end up waiting. Performing synchronous I/O will 
cause your thread to wait, as will calling one of the Win32 wait 
or sleep routines. Calling GetMe$sage( ) will also cause a thread 
to wait if no message is available. In 
critical situations, perhaps a 
PeekMessagef ) call would suffice, and 
would not incur a wait. Since, these 
waits are explicitly caused by the code, 
you should be able to manage and con¬ 
trol where and how often they occur. 

Other types of waits are more subtle. 

For example, a page fault can be 
incurred when a thread attempts to 


access a particular location in memory. It's difficult to predict 
when such a page fault might occur. You can reduce the 
chances of a page fault by keeping commonly accessed data in 
close proximity in memory and by reusing the same memory 
buffers whenever possible. You can even lock portions of the 
process's virtual address space by calling Vi rtual Lock(), but 
this should be reserved for fairly small amounts of memory 
since it can cause overall system performance to suffer. SMP 
machines present an added complication in that each proces¬ 
sor may have its own cache that needs to be kept coherent 
with the cache of all the other processors as well as with main 
memory. The processors essentially have to synchronize their 
access to areas of memory that are referenced by more than 
one cache, which can cause excessive overhead if several 
threads often run at the same time and attempt to modify the 
same data. For this reason, it helps to avoid the use of global 
variables that are modified by several threads (even if the 
access to those variables is protected by synchronization 
objects). 

In a client-server scenario, there is also an issue of how 
many worker threads should be created in the server to han¬ 
dle requests from clients. Entire dissertations have been writ¬ 
ten on this subject, so I will merely summarize the relevant 
advice. Using a single thread to handle all requests forces ser¬ 
ial processing of the requests and is clearly a waste of proces¬ 
sor bandwidth on SMP machines. Even on a single processor 
system, if the thread needs to wait on a resource, it's more effi¬ 
cient to allow other threads to continue fulfilling requests. At 
the other extreme, creating a thread to handle each request 
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incurs unnecessary context switching overhead if there can be 
a large number of outstanding requests at the same time. 

Theoretically, the ideal number of threads is equal to the 
number of runnable processors on the system, with each 
thread being capable of handling any number of requests. In 
practice, though, since threads invariably need to wait for 
resources at times, having a few extra worker threads will 
reduce the chance of having a processor sit idle while a work¬ 
er thread is waiting. This approach balances efficient concur¬ 
rent processing of requests with minimal thread context 
switching overhead. For simplicity, I often just use a value of 
twice the number of runnable processors as the maximum 
number of worker threads to create. Also keep in mind that 
there is a maximum number of thread handles that can be 
passed to Wai tForMul tipi eOb j ects (). If your design allows for 
the possibility of waiting on all the working threads at the 
same time, you should take that into account when calculating 
the maximum number of worker threads (I wish my system 
had enough processors to exceed that limit!). Here's a code 
fragment that shows my heuristic for setting the maximum 
number of worker threads: 

SYSTEMJNFO syslnfo; 

GetSystemlnfot&sysInfo); 
maxThreads = min(MAX_WAIT_OBJECTS, 

1 * syslnfo.dwNumberOfProcessors); 


Additional Multithreading Tips 

1. Windows developers have had years of practice at 
assuming that for the duration of a message, their application 
has complete control and things won't change out from under 
it. A classic example is calling Fi ndWi ndow() at the point where 
you begin processing a particular message and assuming that 
the returned window handle is valid sometime later during 
the processing of that same message. In reality, of course, the 
application could be preempted at any time during the pro¬ 
cessing of that message, and if that happens, another thread 
may get a chance to process and close the window that was 
the object of the FindWindowO call. The presumption that an 
external object handle or resource is available for some fixed 
amount of time is no longer valid. 

2. The system generally keeps a reference count associated 
with handle-based objects, such as threads. The system does 
not free the memory associated with an object until all refer¬ 
ences to that object handle have been closed. The kernel per¬ 
forms an extra optimization in the case of threads. If a thread 
has terminated and all references to it have been closed, the 
kernel may also reuse that thread object and thread context 
structure for subsequently created threads. In so doing, the 
system can forgo allocating memory for the new thread object. 
This raises two issues. 

First, the operating system can reuse a given thread ID 
once the thread has terminated. For this reason, it's very risky 
to hang onto a thread ID value for long periods of time and 
assume that it references the same thread. Just because the 
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thread ID is still valid does not mean it's the same thread. 
Alternatively, if you need to use the thread ID for some time, 
ensure that it can't be reused during that period of time by 
keeping a reference count to it. As you'll see in a moment, this 
can be accomplished simply by not closing the handle 
returned by CreateThread () until you're done with the thread 
ID. 

Second, if your program does not release its references to 
threads as soon as possible, then you are interfering with the 
kernel's attempts at optimizing thread creation. It might seem 
odd but you can close the last reference to a thread handle 
without destroying the thread (some objects remain in memo¬ 
ry until signaled, even if there are no outstanding references to 
the object). In fact, you are encouraged to do just that. When 
creating a thread that doesn't need to be referenced anywhere 
else in your code, it's tempting to create the thread like so: 

if (!CreateThread(...)) { 

// process error 
} else { 

// continue with other work, let 
// thread exit on it’s own when it’s done 

} 


In this example, CreateThread () is returning a handle that 
is not stored anywhere for a future call to CloseHandl e (). All 
open handles of a process are explicitly closed when the 
process terminates, but this means that the system can't reuse 
that newly created thread object until the process itself termi¬ 
nates. It's more efficient to immediately free the thread handle 
once it's been successfully created. This allows the operating 
system to reuse the thread object after the thread terminates. 

hThread = CreateThread(...); 
if (!hThread) { 

// process error 
} else { 

CloseHandle(hThread); 

// continue with other work 

} 


3. If you just need to know whether an object has been sig¬ 
naled or not, you can pass a timeout value of zero to one of the 
wait functions (e.g., Wai tForSingl eObject()). The wait func¬ 
tion will then test whether the object has been signaled but 
will not wait if it has not been signaled. 

4. In some cases, complex synchronization schemes can be 
avoided by designing a thread to perform a task and then exit. 
Other threads can simply wait for the thread handle to be sig¬ 
naled if they need to know when the work is completed. This 
is especially useful in very linear background tasks such as 
printing. It may not be appropriate for tasks that are per¬ 
formed repeatedly, where the overhead of recreating the 
thread might be excessive. 

5. Don't assume that your process's base priority class is 
normal (NORMAL_PRI0RITY_CLASS). The program manager will 
always create processes with normal priority, but your process 
could potentially be started by some other process. For 
instance, a user could start your process by typing "start 
/LOW app.exe". If your process counts on running at a spe¬ 
cific priority class, then set that when the process first starts 
running by calling SetPriori tyCl ass (). 


Summary 

Efficient multithreaded support is critical for both single 
and multiprocessor systems and relies on good thread design. 
First, design your threads as much as possible around serial 
tasks that can be run in parallel with other tasks. Then mini¬ 
mize shared resources between these threads. Finally, syn¬ 
chronize those threads to avoid any possible data corruption 
or deadlocks. 
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Using Long Filenames from 
16-Bit Code 

Robert Mashlan 



Borland C++ v4.52 
Visual C++ vl.5 


One of the biggest improvements that Windows 95 offers over Windows 3.1 is the 
ability to use long filenames rather than the limited DOS 8.3 format. You might 
expect that only programs written with the Win32 API can use long filenames on 
Windows 95, but this is not the case. One of the secrets of Windows 95 is that 16-bit 
programs, both DOS and Windows, can use long filenames via existing or new API 
functions. This article shows how your 16-bit Wmdows or DOS programs can take 
advantage of long filenames when they are running under Windows 95. 

The VFAT File System 

Microsoft had to implement long filenames in a way that was compatible with 
existing software, and more than a few existing programs depend on the exact 
details of the DOS FAT file system. Long filenames are part of the VFAT file system 
introduced in Windows 95. The VFAT file system runs on top of existing FAT vol¬ 
umes created in DOS. VFAT works by using special extra directory entries for each 
long filename to store the characters used for the filename, along with other infor¬ 
mation. These special directory entries are marked by an "impossible" combination 
of flags and so are ignored by low-level DOS programs that directly access DOS file 
directories and are unaware of long filenames. Windows 95 can thus store extra data 
in directory entries that legacy programs will generally not see — in this case, the 
extra data is the long filename. 

Each long directory name entry has a short name alias for use by programs that 
don't understand long filenames. For instance, the filename "a long filename.txt" 
may have the alias "along~l.txt". The short name aliases can quickly become cryp¬ 
tic, but they do ensure that 16-bit software that is unaware of the new VFAT long file¬ 
names will be able to access files that were created under Windows 95. 

The basic problem for legacy applications — whether 16-bit DOS or 16-bit 
Windows — is that they will by default see only the cryptic short name aliases for 
files that were created by Windows 95. It would be nice if such applications could be 
quickly tweaked to take advantage of the new long filenames, without requiring a 
complete port to 32-bit code (with the resulting loss of compatibility with 16-bit 
Windows platforms). 

Long Filenames from 16-Bit Windows Apps 

Using long filenames in a 16-bit program running under Windows 95 is easier 
than you might think. First, the 16-bit version of the common dialog box library 
included with Windows 95 can be made to support long filenames. You can do this 


Robert Mashlan is an independent software consultant doing business as R2M Software 
Company, specializing in Windows device drivers. He may be reached at (503) 738-0849 
or rmashlan@r2m.com on the Internet. His PGP public key fingerprint is 17 F9 F3 35 
E8 3C FE 7A B7 CB 19 FB EC 73 77 94. WWW surfers may read his home page at 
http://r2m.com/~rmashlan. 
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Listing 1 Ifnames.h — Declaration for long 
filename functions 


II listing 1, Ifnames.h 

#i fdef_cplusplus 

extern "C" { 
fendif 

fdefine LFN_HAX_PATH 260 

fdefine SFN_MAX_PATH 80 

int lfn_api( const char ‘rootname ); 

unsigned GetShortPathNamet const char ‘filename, 

const char ‘shortname, unsigned size ); 
unsigned GetLongPathNamet const char ‘filename, 

const char ‘longname, unsigned size ); 
int 1fn_mkdir( const char ‘path ); 
int lfn_rmdir( const char ‘path ); 
int lfn_chdir( const char ‘path ); 
int lfn_unlink( const char ‘path ): 

int lfn_rename( const char ‘oldname, const char ‘newname ); 

int lfn_access( const char ‘path, int amode ); 

int lfn_open( const char ‘path, int mode, int smode ); 

FILE *1fn_fopen( const char ‘filename, const char ‘mode ); 
int lfn_findfirst( const char ‘path, int attrib, 
struct lfn_find_t ‘finfo ); 
int 1fn_findnexti struct lfn_find_t ‘finfo ); 
void 1fn_findclose( struct lfn_find_t ‘finfo ); 


struct lfn_find_t 
{ 

char attrib; /* attribute 
unsigned wr_time; /* time 

unsigned wr_date; /* date 

unsigned long size; /* size 

char name[LFN_MAX_PATH]; /* 

int findhandle; 

}; 


byte for matched 
of last write to 
of last write to 
of file 

asciiz filename 


file */ 
file */ 
file */ 
*/ 
*/ 


fifdef _cplusplus 

} 

fendif 

/* End of File */ 


Listing 2 Ifnames.c — Implementation of 
long filename functions 


findude <stdio.h> 

(/include <stdlib.h> 
findude <dos.h> 
findude <io.h> 
findude <fcntl.h> 
findude <sys\stat.h> 
findude <string.h> 
findude <errno.h> 

findude "Ifnames.h” 

fdefine TEST // defines main to make test program 

fifdef _MSC_VER 
fif (_MSC_VER>-600) 
fdefine SREGS _SREGS 
fdefine REGS _REGS 
fdefine intdosx _intdosx 
fundef FP_0FF 
fundef FP_SEG 

// need to do this for MSC, because the MSC version requires 

// an Lvalue for the pointer! 

fdefine FP_0FF(p) (unsigned short)(p) 

fdefine FP_SEG(p) (unsigned short)((unsigned long)\ 

(void _far *)(p)»16) 
fendif 
fend if 

static int DoDosCalK unsigned func, union REGS *r, 
struct SREGS *s ) 

// helper function to call DOS interrupt 
( 

r->x.ax - func; 


Listing 2 continued 


intdosx(r,r,s); 

If(r-)x.cflag) 

_doserrno - r->x.ax; 
else 

_doserrno - 0; 
return r->x.cflag; 


fdefine SETPTR(seg.off,ptr) s.seg - FP_SEG((ptr)),\ 
r.x.off - FP_0FF((ptr)) 

int lfn_api( const char ‘rootname ) 

// returns non-zero if volume supports long file names 
1 

union REGS r; struct SREGS s; 
char filesystem[401; 

SETPTREes,di.filesystem); 
r.x.cx - sizeof(filesystem); 

SETPTR(ds,dx,rootname); 
if(DoDosCal1(0x71a0.&r,&s)) 
return 0; 

return r.x.bx 8 0x4000; // check for FS_LFN_APIS flag 


unsigned GetShortPathNamel const char ‘filename, 

const char ‘shortname, unsigned size ) 

( 

union REGS r; struct SREGS s; 
if(size<SFN_MAX_PATH) // path too small? 
return 0; 

SETPTRtds,si,filename); 

SETPTRtes,di.shortname); 
r.x.cx - 1; 

if(DoDosCal1(0x7160,Sr,Ss)) 
return 0; 

return strlen(shortname); 


unsigned GetLongPathNamel const char ‘filename, 

const char ‘longname, unsigned size ) 

{ 

union REGS r; struct SREGS s; 

If(size<LFN_MAX_PATH) // path too small? 
return 0; 

SETPTR(ds,si.filename); 

SETPTR(es,di.longname); 
r.x.cx - 2; 

i f( DoDosCal 1 (0x7160,&r.&s)) 
return 0; 

return strlen(1ongname>; 


int lfn_mkdir( const char ‘path ) 
( 

union REGS r; struct SREGS s; 
SETPTRtds,dx,path); 
if(DoDosCal1(0x7139, Sr ,8s)) 
return -1; 
return 0; 


int lfn_rmdir( const char ‘path ) 
{ 

union REGS r; struct SREGS s; 
SETPTR(ds.dx.path); 
if(DoDosCall(Ox713a,8r,8s)) 
return -1; 
return 0; 


int lfn_chdir( const char ‘path ) 
{ 

union REGS r; struct SREGS s; 
SETPTRtds,dx,path); 
ifIDoDosCall(0x713b,8r,8s)) 
return -1; 
return 0; 


int lfn_unlink( const char ‘path ) 

{ 

union REGS r; struct SREGS s; 

SETPTRtds,dx,path); 

r.h.cl - _A_ARCH|_A_SYSTEM|_A_RD0NLY; 
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Listing 2 continued 


r.h.ch - 0; // must match 
r.x.si - 0; // no wild cards 
if(DoDosCal1(0x7141,&r,Ss)) 
return -1; 
return 0; 


int lfn_rename( const char ‘oldname, const char ‘newname ) 
{ 

union REGS r; struct SREGS s; 

SETPTR(ds.dx.oldname); 

SETPTR(es,di.newname); 
if(DoDosCal1(0x7156,&r.&s)) 
return -1; 
return 0; 


int lfn_access( const char ‘path, int amode ) 

{ 

union REGS r; struct SREGS s; 
r.x.bx - 0; // get extended attributes 

SETPTR(ds.dx.path); 
if (DoDosCal l(0x7143,&r,!is)) 
return -1: 

if(!(amode&0x02) || !(r.x.cx 8 _A_RD0NLY) ) 
return 0; 
errno - EACCES; 
return -1; 


typedef unsigned long DWORD; 

typedef struct .FILETIME ( 
DWORD dwLowDateTime; 

DWORD dwHighDateTime; 

} FILETIME; 


typedef struct _WIN32_FIND_DATA { // wfd 
DWORD dwFi1eAttributes; 

FILETIME ftCreationTime; 

FILETIME ftLastAccessTime: 

FILETIME ftLastWriteTime; 

DWORD nFi1eSizeHigh; 

DWORD nFi1eSizeLow; 

DWORD dwReservedO; 

DWORD dwReservedl; 

char cFileName[ LFN.MAX.PATH ]; 

char cAlternateFileNameC 14 ]; 

} WIN32.F1ND.DATA; 

int lfn.findfirst( const char ‘path, int attrib, 
struct 1fn.find.t ‘finfo ) 

( 

WIN32.FIND.DATA finddata; 
union REGS r; struct SREGS s; 

SETPTR(ds.dx.path); 

SETPTRtes,di,&finddata); 
r.x.cx - attrib; 

r.x.si - 1; // MS-DOS format time/date 
if(DoDosCal1(0x714e,&r,&s)) 
return -1; 

finfo->findhandle - r.x.ax; // save find handle 
strcpy(finfo->name.finddata.cFileName); 
finfo->size - finddata.nFi1eSizeLow; 
finfo->wr_date - (unsigned) 

(finddata.ftLastWriteTime.dwLowDateTime >> 16 ); 
finfo->wr_time - (unsigned) 

(finddata.ftLastWriteTime.dwLowDateTime & Oxffff ); 
finfo->attrib - finddata.dwFi1eAttributes & 0x7f; 
return 0; 
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by specifying the OFN_LONGNAMES flag for the FI ags member of 
the OPENFILENAME structure passed to GetOpenFi 1 ename() and 
GetSaveFi 1 eName(). This flag isn't defined in the Windows 3.1 
header files, so you will have to define it yourself: 

(/define 0FNJ.0NGNAMES 0x002000001. 

This flag is ignored by the older versions of the common dia¬ 
log box library, so you don't have to conditionally OR the bit in 
at runtime if you detect the presence of Windows 95. 

When you use this flag, the dialog box displays (and 
GetOpenFi 1 ename and GetSaveFileNameO functions return) long 
filenames. However, there is a problem if you use the 
OFN_ALLOWMULTISELECT flag with these functions. This flag lets 
the user select more than one file, and causes the function to 
return a string that starts with the path, followed by each select¬ 
ed filename, separated by spaces. Using spaces to separate the 
names is problematic, now that users can embed spaces in a 
filename. For that reason, whenever a 32-bit Win95 or NT pro¬ 
gram uses the OFN_ALLOWMULTISELECT flag and the common dia¬ 
log encounters a long filename containing a space, it returns the 
short alias name of that file (if there's no space in the name of 
the file, the correct long filename is returned). Windows 95 is a 
little different than NT: if there is a space in one of the directory 
names of the path being searched, it does not use the alias name 
of that directory in the returned string, which means you can't 
just search for the first space to locate the first filename 
returned. Finally, the 16-bit version of the common dialog box 
code under Windows 95 just avoids the entire issue by return¬ 
ing short filenames. 

Second, you can work with long file¬ 
names from a 16-bit Windows program 
running under Windows 95 by using some 
of the existing API functions. _1 created 
and _1 open( ) can use both short filenames 
and long filenames. These functions return 
file handles which are used with _1 wri te ( ), 

JreadO, JlseekO and _1 closet). 

The Windows function Open Fi 1 e(), 
however, does not understand long file¬ 
names because of a limitation of 
OFSTRUCT, the structure you pass to 
Open Fi led. For the purpose of returning 
the filename, OFSTRUCT contains a charac¬ 
ter array hard-coded to be 128 characters 
long; under Windows 95, a long filename 
may be up to 260 characters long. 

Microsoft silently added to the 16-bit 
Windows 95 API a function called 
OpenFi 1 eEx (), with a corresponding 
structure of type OFSTRUCTEX, which han¬ 
dles long filenames. These functions are 
defined in the 16-bit windows.il file 
included in the Windows 95 DDK. If you 
want to use this function from a 16-bit 
program designed to also run under 
Windows 3.1, you can use 
GetProcAddress( ) to obtain a pointer to 
the functions (I explain how to do this in 
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Listing 2 continued 


int 1 -fn_f 1 ndnextC struct lfn_find_t *finfo ) 

{ 

WIN32_FIN0_DATA finddata; 
union REGS r; struct SREGS s; 

SETPTR(es,di.Sfinddata): 
r.x.si - 1; // use dos time 
r.x.bx - finfo->findhandle; 
if(OoDosCal1(0x714f,&r.&s)) 
return -1; 

strcpy(finfo->name,finddata.cFi1eName); 
finfo->size - finddata.nFileSizeLow; 
finfo->wr_date - (unsigned) 

(finddata.ftLastWriteTime.dwLowDateTime » 16): 
finfo->«r_time - (unsigned) 

(flnddata.ftLastWriteTime.dwLowDateTime & Oxffff ); 
finfo->attrib - finddata.dwFi1eAttributes S 0x7f; 
return 0; 


void 1 fn_findclose( struct lfn_find_t *finfo ) 
( 

union REGS r; struct SREGS s; 
r.x.bx - finfo->findhandle; 

DoDosCall(0x71al,&r,&s); 


int lfn_open( const char ‘path, int mode, int smode ) 
{ 

union REGS r; struct SREGS s; 

SETPTR(ds,si.path); 

r.x.bx - mode S 0x3; // read/write flags 
if(mode J O.CREAT) { 

swi tch( smodeit SJ READ | SJWRITE)) ( 
case 0: 

r.x.bx |- 0x0010; // deny read/write 
break; 

case S_I READ: 
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"Accessing Win95 Functions from 16-Bit Programs/' listed in 
the Bibliography). 


Accessing Long Filenames from DOS 

When long filenames were added to Windows 95, 
Microsoft provided a way for DOS programs, as well as 16-bit 
Windows programs, to use long filenames via the 15-year-old 
DOS I NT 21 h interface. Although these are in fact new DOS 
functions, you must be running the Windows 95 GUI in order 
to use them. For instance, you cannot use them from "Single 
Application Mode," nor while autoexec. bat is running. This is 
because the VFAT file system is implemented as a VxD that 
runs only while the GUI portion of Windows 95 is running. 
There is no fall-back code in the MS-DOS portion of Windows 
95 that can handle long filenames when Windows 95 itself is 
not running. 

16-bit Windows programs can also take advantage of these 
new DOS functions. Protected-mode Windows 3.0 and 
Windows 3.1 can be thought of as DOS extenders that come 
with a nice graphics library. A DOS extender allows an appli¬ 
cation to run in protected mode, while still allowing the appli¬ 
cation to use DOS functions. One of the jobs of a DOS exten¬ 
der is to make the necessary conversions between using pro- 
tected-mode pointers and real-mode pointers in DOS calls. 
For instance, it is perfectly permissible for a Windows pro¬ 
gram to call the DOS I NT 21 h, function 6Ch in protected mode 
to open a file. In fact, this is what happens when you use the 
C runtime library functions fopenO or open() from a 16-bit 
Windows program. The point is that 16-bit Windows pro- 
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grams can (and usually must) call DOS functions to work. 

Example Code 

1 fnames. h (Listing 1) and 1 fnames. c (Listing 2) make up a 
small library and an example application using long filename 
DOS functions. You can compile the source as a DOS pro¬ 
gram, or you can compile it via the EasyWin libraries in 
Borland C++ to create a 16-bit Windows program. The pro¬ 
gram accepts two command-line parameters: a command 
name (as shown in Table 1) and a filename. 

If the second parameter is a long filename with spaces, you 
can delimit the filename with quote characters. When the C 
runtime start-up code parses the arguments on the command 
line, it will strip the quotes and put the filename into one ele¬ 
ment of the argv array. 

The function 1 f n_api () (Listing 2) allows you to detect 
whether long filenames are available for the file system. You 


Listing 2 continued 


r.x.bx |- 0x0020; // deny write 
break; 

case SJWRITE: 

r.x.bx |- 0x0030; // deny read 
break; 

case S_IWRITE|S_IREAD: 

r.x.bx |- 0x0040; // deny none 
break; 

) 

1 

r.x.cx - _A_N0RMAL; 
r.x.dx - 0; 

if(mode A 0_CREAT ) r.x.dx |- 0x0010; 
if(mode 8 0_TRUNC ) r.x.dx j- 0x0002; 
if(mode 8 0_EXCL ) r.x.dx |- 0x0001; // file must exist 
if(DoDosCal1(0x716c,&r,&s)) 
return -1; 

return r.x.ax; // return file handle 


FILE *lfn_fopen( const char ‘filename, const char ‘mode ) 
t 

char shortnameCLFN_MAX_PATH3; 
if( strchrtmode,’a’) || strchrtmode, V) ) { 

// if the file doesn't exist - create it 
if( 1fn_access(fi1ename.OO) ) ( 
int hf - 1fn_open(fiiename, 

0_CREAT|0_TRUNC|0_WR0NLY,0); 
close(hf): 

) 

) // convert a long name to a short name, if needed 
GetShortPathNametfilename,shortname,sizeof(shortname)); 
return fopen(shortname.mode); 


#ifdef TEST 

int main! int argc, char “argv ) 

{ 

if(argc>2) t 

if( strcmpl(argvCl],"api”)—0 ) ( 

printf("Long filenames Ksavailable for V'SSsVWn", 
ifn_api(argv[2]:"not ",argv[2]>; 

) else if( strcmpi(argv[l],"shortname”)—0 ) ( 
char buf[SFN_MAX_PATH]; 

if( GetShortPathName(argv[2].buf,sizeof(buf)) ) { 
printf("Short name of its is %s.\n",argv[2],buf): 
{ 

int i; 

for(i-0;i<strien(buf);i++) 

printf(”'Kc' %02x ”.buf[i],buf[i]): 

1 

1 else 

printfC'Can't convert to its to a short name.W, 
a rgv [ 2]); 

} else if( strcmpi(argv[13,”longname")==0 ) ( 
char buf[LFN_MAX_PATH]; 
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give the function a root directory name, for instance, "C:\\", 
and it returns non-zero if long filenames are supported on 
that volume. 1 fn_api () calls INT 21h, function 0x71A0, which 
also provides other interesting information about the volume; 
refer to the references in the bibliography for more informa¬ 
tion on this DOS call. 

GetShortPathName () and GetLongPathNamef ) are provided 
for the purpose of converting between a long filename and its 
short 8.3 format alias filename. The original filename may be 
either short or long for either function. 

IfnjnkdirO, 1 fn_rmdi r(), lfn_chdir(), lfn_unlink(), 
1 fn_rename(), and 1 fn_access( ) are long filename equivalents 
to the C runtime library functions mkdi r(), rmdi r( ), chdi r(), 
unlink!), renamed, and access!). One difference between 
these functions and the corresponding library functions is 
that they do not set the standard runtime library variable 
errno; however, the do set _doserrno correctly. 


Listing 2 continued 


if( GetLongPathNamelargv[2],but,sizeof(buf)) ) 
printf("The long name of \"%s\" is \”%s\".\n", 
argv[2],buf); 

else 

printfC'Can't convert to \"%s\” to long name.Vn", 
argv[2]l; 

) else If( strcmpi(argv[l],"mkdir")—0) { 

1f( Ifn_mkdir(argv[2]) ) 

printfC'dos error Jd\n",_doserrno); 

) else 1 f( strcmpi(argvfl],"chdir")—0) { 
if( lfn_chdir(argv[2]) ) 

printf("dos error %d\n",_doserrno); 

} else if( strcmpi(argv[l],"rmdir”)—0) ( 
if( lfn_rmdir(argv[2]) ) 

printfC'dos error %d\n”,_doserrno): 

) else 1f( strcmpi(argv[l],"exist")—0) ( 
pri ntf C'Tiie file \"%s\” does %sexist.\n”, 
argv[2],lfn_access(argv[2],0)?”not 
} else if( strcmpi(argv[l]."del")-—0) { 
iff lfn_unlink(argv[2]) ) 

printfC'dos error Jd\n”,_doserrno); 

) else iff strcmpifargv[13,"readfi1e”)—0 ) ( 

FILE *f - 1fn_fopenfargv[2],"rb"); 
if(f) ( 

fseekff,0,SEEK_END); 

pri ntf ("The size of \”%s\" is tld.\n". 

argv[2],ftell(f>); 

fclose(f); 

) else 

printf("Fai1ed to open \"%s\".\n",argv[2]); 

} else iff strcmpifargv[l],"writefi 1 e")~0 ) ( 

FILE *f - lfn_fopen(argv[2],"w"); 
iftf) ( 

fprintfff,"This file is named \"*s\"\n", 
argv[2]); 
fclose(f); 

} else 

printff"Fai1ed to open \"Js\”.\n",argv[2]): 

) else iff strcmpi(argv[l],"dir")—0 ) ( 
struct lfn_find_t f; int i: 
forfi-l fn_findfirst(argv[2],_A_N0RMAL,&f); 

i—0: 1—1 fn_fi ndnext (&f) ) 
printf("%s Xd/Xd/Xd X02d:X02d:X02d Xlu\n", 
f.name,(f .wr_date»5)&0xf ,f .wr_dateS0xlf, 

(f .wr_date>>9)+1980,f .wr_time»ll, 
(f.wr_time»5)&0x3f, (f .wr_time&0xlf )*2, 
f.size); 

1fn_findclosef&f); 

) else 

printfC'unrecognized command %s\n".argv[l]): 

) else 

printff"syntax: lfnames cmd fi1ename\n"); 
return 0; 

) 

#endif 

/* End of File */ 


1 fn_f1 ndfi rst( ) and 1 fn_fi ndnext () replace the C runtime 
library functions _d os_findfi rst( ) and _dos_f i ndnext( ). An 
extra function, 1 fn_f1 ndcl ose!), is required by the underlying 
DOS API to free resources associated with using the long file¬ 
name enumeration functions. These functions use the struc¬ 
ture lfn_find_t (defined in Listing 1), which has the same 
members with the same meanings as the f i nd_t structure used 
for _dos_f i ndf i rst(). 

The lfn_open() function is a replacement for the open!) 
function available with DOS C runtime libraries. The file han¬ 
dle returned from this function can be used with any other 
function that uses a file handle, but there is one important dif¬ 
ference between this function and the standard open () func¬ 
tion. Internally, the runtime library version of open! ) stores a 
file handle in a table which marks if the file is open in binary 
or text mode. If a file is open in text mode, the runtime library 
will make newline conversions during I/O. No such provision 
has been made in 1 f n_open 0, so a file will always be opened in 
binary mode whether or not you use the text mode flag. 

1 fn_fopen () is a replacement for the C runtime library 
function f open (). It will create the target file with a long file¬ 
name (if the file doesn't already exist, then open the file using 
its short name alias and f open (). Any runtime library function 
that accepts a FILE * as a parameter can use the pointer 
returned by this function. 

Character Conversions 

It is important to note that, like the old DOS functions to 
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Table 1 

Command documentation for test program 

command 

function 

description 

api 

lfn_api 

check for long file name API on volume 

shortname 

GetShortName 

convert file name to short file name 

longname 

GetLongName 

convert file name to long file name 

mkdir 

1fnjnkdir 

make a directory 

chdir 

lfn_chdir 

change to directory 

rmdir 

lfn_rmdir 

remove directory 

exist 

lfn_access 

check for file existance 

readfile 

1fn_fopen 

read file (displays length of file) 

writefile 

1fn_fopen 

creates a file and writes to it 

dir 

lfn_findfirst, 1fn_findnext, 

1 fn_.fi ndcl ose 

simple directory listing using a file mask 

del 

lfn unlink 

deletes a file 
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which they correspond, these DOS 
functions use the OEM character set, 
not the ANSI character set. If you call 
these functions in a 16-bit Windows 
program, you will have to use 
AnsiToOemO and OemToAnsi (); you'll 
need to convert between the two char¬ 
acter sets if you display your filename 
strings in a Windows ANSI font. For 
instance, if you call GetOpenFileO with 
the 0FN_L0NGNAMES flag to retrieve a long 
filename, you must convert the 
returned filename to the OEM character 
set via Ansi ToOem( ) to use it with a DOS 
function. 

Conclusion 

I encourage you to explore the new 
long filename DOS APIs, since they 
have capabilities not covered by this 
article. For instance, long filename 
entries have a last access date, which is 
the date when the file was last read or 
modified. DOS utilities such as virus 
scanners should save and restore this 
last access date when scanning a file, 
since a virus scan shouldn't really count 
as the user accessing the file. 

If you develop or maintain a 16-bit 
Windows or DOS program, porting to 
the Win32 API in order to take advan¬ 
tage of long filenames under Windows 
95 may not be feasible. With the func¬ 
tions demonstrated here, you can quick¬ 
ly add some Windows 95 functionality 
to your existing 16-bit software. 
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Thuan Q. Pham and Pankaj K. Garg 
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[Editor's note: This review was provided by Paula Tomlinson.] 
Given the many generic beginning and intermediate level 
Win32 programming books, I take special interest in books 
that profess to cover a single topic in an advanced or exhaus¬ 
tive manner. Though multithreaded programming is not 
exactly a small topic, in most Win32 programming books it 
rates a single chapter dealing with synchronization objects. 
This book deals exclusively with multithreaded synchroniza¬ 
tion issues on Windows NT. I'm not quite sure why Windows 
95 was excluded, other than perhaps Windows 95 just wasn't 
available when they were doing the final editing of the book. 
Another reason might be that they were focusing on an oper¬ 
ating system that supports multiple processors and where, 
consequently, careful thread synchronization is even more 
critical. The code samples are relevant to both Windows 95 
and Windows NT, however. 

Anyone who is comfortable with basic Windows program¬ 
ming should be able to pick this book up and read it straight 
through without difficulty. The authors first explain how 
processes and threads work on Windows NT as well as the 


basic synchronization primitives available in Win32. The rest 
of the book deals with common multithreaded scenarios. 
There are lots of straightforward examples with clearly 
explained problem statements. It's always a challenge to draw 
or graph synchronization problems, but the diagrams here (as 
well as the robot arms and conveyer belts) are as effective as 
any I've seen. As is the case with many software books these 
days, the license on the back page of the book does not give 
you the right to distribute the source code examples, so you 
presumably cannot use them for inclusion in your own com¬ 
mercial programs. In fact, you are allowed to make exactly 
one copy of the floppy, for backup purposes only. Even 
though you can't lift the source code examples directly, they're 
still useful teaching mechanisms. If you read this fairly small 
book (227 pages, including the index) from cover to cover and 
carefully follow all the examples, you will come away with a 
basic working knowledge of multithreaded techniques and 
issues. 

Although the book is fairly basic, it does discuss some 
sophisticated topics, such as "fair" scheduling. It's one thing 
to ensure that your program has no potential for corrupting 
shared resources and no deadlocks or race conditions between 
threads. It's quite another thing to design your code to most 
efficiently and fairly allow access to those shared resources, 
especially in scenarios where there can be multiple readers 
and writers vying for the shared resource. There is lots of 
good discussion of the efficiency and comparative effective¬ 
ness of various solutions (in terms of number of context 
switches, etc.). The authors' approach is to describe the basic 
synchronization primitives available on Windows NT and 
then use these to solve such common multithreaded synchro- 
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nization problems as multiple-reader single-writer. I like this 
approach much better than the more common tactic of making 
up silly examples just to demonstrate the syntax of each syn¬ 
chronization primitive. Most of the examples are only two- to 
four pages of source code and are quite easy to read and fol¬ 
low. 

Somewhat more involved is the discussion of monitors. In 
this context, "monitor" is a somewhat standard operating sys¬ 
tem term for the notion of encapsulating the synchronization 
method and thread scheduling issues with the shared 
resource that is to be protected. C++ lends itself quite well to 
this concept, so most of the discussion is in reference to C++ 
and sample monitor code is written in C++. By encapsulating 
the operations of accessing the shared data as methods (such 
as read and write), you can hide the work of synchronizing 
that access from the caller. Thus, you don't have to rely on the 
caller to remember to lock the resource before accessing it and 
unlock it aferwards. In very simple instances, you can use crit- 
icial sections within the monitor — which is very efficient. You 
can also change the way you implement the sharing of that 
resource (such as allowing multiple readers) without neces¬ 
sarily having to change the interface to the monitor. 

The discussion on deadlocks was also well researched and 
fairly thorough. In fact, the book was surprisingly practical 
and non-academic on this topic. Several approaches to resolv¬ 
ing deadlocks are discussed, along the whole gamut from just 
ignoring them (if the chance of a deadlock is rare and provi¬ 
sions are allowed for terminating a deadlocked thread) to 



designs that completely prevent the possibility of a deadlock 
ever occurring. An obvious tradeoff here is between code 
complexity and code robustness. Deadlocks aren't as mysteri¬ 
ous as many people seem to think. A set of well-defined con¬ 
ditions must be met for a deadlock to occur (or have the pos¬ 
sibility of occurring) and the authors present those here. 

After years and years of programming for the single- 
threaded DOS and 16-bit Windows operating systems, many 
developers may have a lot to learn about multithreaded pro¬ 
gramming. It's pretty easy to spot a big, clunky single-thread¬ 
ed program that appears unresponsive at times, as well as a 
program that creates so many threads it spends most of its 
processing time context switching between them. A thorough 
discussion of how many threads you should use in your pro¬ 
gram and how to allocate tasks to each of those threads is the 
one thing that I thought was largely missing from this book. 
Still, for all but the most complex applications, this book is a 
sufficient reference all by itself. I also fervently hope that these 
smaller, focused books are a new trend in the computer book 
publishing field. 


Windows 95 System Programming Secrets 
Matt Pietrek 
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778 pages 
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Pity the poor publishers of technical books. They generally 
have to acquire, edit, and market books that they can't com¬ 
prehend a single word of. Therefore, it's understandable that 
they resort to simplifying strategies, such as dividing all books 
into two categories: "Secrets" and "For Dummies." Now you 
might think that is an easy distinction to make, but I note that 
on the registration card of my copy of Windows 95 Secrets (a 
quite decent book for power users), someone has blacked out 
"For Dummies" and inked in "Secrets." I have no doubt that 
there are lengthy meetings with the publisher, involving brass 
all the way up to vice presidents, just to debate whether a par¬ 
ticular book is better labeled "Secrets" or "For Dummies." 

This particular book got labeled "Secrets," and I think the 
publisher's brain trust made the right decision here. The book 
is really about the results of reverse-engineering expeditions 
into Windows 95, so much of the information can qualify as 
"secret," in the sense that you can't discover it from 
Microsoft's documentation. The author is one of the great 
warriors of PC reverse-engineering, whose ranks include 
Andrew Schulman, Geoff Chappell, Paul Bonneau, Roger 
Alley, Frank Van Gilluwe, Ralf Brown, and many others. The 
reason so many talented reverse engineers exist is simple: the 
Microsoft documentation for the Windows API fails to cover 
many important issues. Some people assume that reverse¬ 
engineering is needed only to discover obscure, undocument¬ 
ed features that programs really shouldn't take advantage of. 
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The truth is, however, you need reverse-engineering to under¬ 
stand such fundamental Windows operations as messaging 
and window painting. 

One of the best pieces of the book is Chapter 3, which cov¬ 
ers modules, processes, and threads. Understanding the basic 
data structures behind these concepts is essential if you want 
an accurate mental model of how Windows 95 works. A good 
high-level understanding of Windows is a prerequisite here, 
however. For example, you'll need to understand the high- 
level description of thread priorities in this month's 
"Understanding NT" before you delve into the much lower- 
level description here. This chapter also has the only technical 
description I've seen of how structured exception handling 
(SEH) is actually implemented in Windows 95. 

Chapter 4 covers USER and GDI and, like those subsys¬ 
tems, is a bit of a hodgepodge. I think the most important 
topic in this chapter is the coverage of the messaging system. 
A good mental model of Windows 3.x messaging requires an 
understanding of why SendMessageO is a complex function 
(e.g., it has to handle task switching). Under Windows 95, life 
is further complicated by the mixture of 16-bit windows (i.e., 
their window procedure is 16-bit code) and 32-bit windows. 
This is messy stuff, and though you may write a lot of code in 
blissful ignorance, it's not hard to construct real-life scenarios 
that require you to understand much more about messaging 
than you can glean from Microsoft documentation. This chap¬ 
ter also includes updated descriptions of the WND internal win¬ 
dow structure (handy for systems programmers who com¬ 
monly step into Windows code while debugging). GDI is only 
a small portion of this chapter. 

Chapter 5 covers memory management. "What?" you say, 
"Didn't all our memory management problems get wiped out 
by Windows 95?" Not really. While it's true that you can quit 
worrying about six different memory models and far versus 
near pointers, any program that makes intensive use of mem¬ 
ory should be written by someone who understands how the 
operating system manages memory. Without that under¬ 
standing, you cannot reason intelligently about how to mem¬ 
ory efficiently use, as the article "Don't Use Memory-Mapped 
Files" in this issue demonstrates. This chapter contains a com¬ 
petent overview of Win95 memory management, and also 
descends to the level of providing pseudocode for Win32 
memory management functions. 

I think the chapters I've described are the most important, 
but the book also covers various VxD-level issues, 16-bit mod¬ 
ules and tasks (as they exist under Win95), the PE and COFF 
OBJ file formats, spying on other processes, and more. An 
appendix shows you how to easily access undocumented 
functions in the Win95 kernel that Microsoft explicitly tries to 
prevent you from accessing via more conventional means. 

As usual, the publisher promises you "valuable source 
code" on the cover of the book, but then restricts your use of 
it in the fine print in the back of the book. I have a new idea 
for solving this problem. California leads the country in both 
computer technology and techno-law — this is the state that 
single-handedly forced computer makers to start advertising 
the true size of their video screens. How about we start a let¬ 
ter-writing campaign to the California attorney general? If 
California prohibited such deceitful practices by computer 


book publishers, that would almost certainly be the end of the 
old bait-and-switch code disk technique. Anyone have an 
email address for the AG? 

This book is best suited for experienced programmers who 
are already up to speed on the workings of Windows 3.x. This 
is not a good book for programmers who are uncomfortable 
with assembly language, or completely ignorant of the Intel 
protected-mode architecture. The reverse-engineering this 
book provides should help more programmers truly under¬ 
stand Windows 95 more quickly. 
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Gene Wang 
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I had mixed emotions when I learned that my proposed 
talk for Software Development '96, entitled "How to Write 
Truly Awful Programming Books," was rejected. I hoped that 
the rejection was based on a desire to prevent more bad books 
from being written, but I feared the rejection might be based 
on the assumption that all the attendees would already know 
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how to write bad books. Certainly, one of the premises of my 
talk was to have been that every single computer programmer 
in the world will write at least one book before the year 2010. 
If you have not yet been contacted by a book publisher, it can 
only be because they are having trouble locating your address. 
Or perhaps they assumed you would respond to one of the 
"Authors Wanted" messages they periodically post online. 

One side effect of the fact that everyone is required to write 
a book is that you get good books, bad books, and mediocre 
books, but you also get quirky books, like this one. Gene Wang 
(currently of Symantec) was an important manager who 
departed under a cloud during the long fall of the House of 
Kahn. His story included accusations, counter-accusations, 
search warrants, police confessions, lawsuits — he was the 
Silicon Valley O.J. of his time. But you'll have to wait for the 
$29.95 video to find out about that, for Mr. Wang has chosen 
to write, of all things, a job handbook for programmers. 

This book tells you how to write a resume, how to behave 
in a job interview, what tools you should be using, what com¬ 
ponent programming is, how to optimize the software lifecy¬ 
cle (why not — it only takes a few pages!), how to select the 
right company for you, how to tell when it's time to move on, 
and so on. The book is filled with extensive quotes from 
Gene's friends/coworkers, including Gordon Eubanks 
(Symantec), Brad "it will definitely ship this year" Silverberg 
(Microsoft), Walter Bright (Symantec C++ author), and others, 
and there are plenty of Dilbert cartoons. 

I'm unfortunately not a good person to judge the merits of 
this book. Part of my problem is that I somehow became an 




industry insider when I wasn't looking. So, for example, when 
famous programmer X expounds in this book on how to 
become a successful programmer, I couldn't help recalling less 
than flattering descriptions of how programmer X actually 
became successful, authored by his past coworkers. However, 
an odd book is better than a bad book, or a boring book, or 
even a mediocre book (in my book, anyway). I think Gene 
Wang has a perspective that's skewed just enough from the 
norm to qualify as quaint, if not downright entertaining. 
Here's an example of the sort of thing that tickled my funny 
bone, some advice on the proper attitude when preparing a 
resume: 

There is a cultural bias in the United States against "tooting 
your own horn." 

I don't know exactly where in the U.S. programming scene 
Gene detected this cultural bias, but I live a few blocks from 
Microsoft, and the horn-tooting here is so loud I have to keep 
my windows closed just to hear myself think. 

I expect we will see more and more books like this over 
time; it makes good sense for software company executives to 
write books. The book helps publicize the executive's compa¬ 
ny, making it seem more important, and can help communi¬ 
cate the company's mission under the guise of providing gen¬ 
erally useful information. For example, after you've learned to 
write a resume and conduct a job interview, page 187 of this 
book informs you that Symantec "has over 200 job openings 
for programmers, and new jobs are always opening up." 

Nicely finessed! (Their Web site is 
www.Symantec.com, if you're interested.) 
Such a book also gives the executive's 
resume a boost, which is helpful when 
the inevitable time arrives for a change 
of scenery and a boost in compensation. 
In that sense, this book is almost self- 
referential. I think Gene Wang may 
have authored the sliest computer book 
of the year. 
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Porting to WIN 32 
Thomas Lauer 
Springer-Verlag 
New York, 1996 
428 pages 
$39.95 

ISBN 0-387-94572-5 


In the February issue, I reviewed a 
book called Migrating to Windows 95, 
concluding that it failed by failing to 
stick to the topic. Here is a new book 
(translated from the German original) 
that attempts to cover much the same 
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(text continued from page 62) 

the subject, with somewhat more success. This book's more 
than 400 pages are crammed with text, not code and screen 
shots. The author rambles across hundreds of topics, most of 
them fairly well related to the general problem of portability 
to and across Windows platforms. 

I found plenty in this book to disagree with (I don't plan to 
completely switch to using message crackers, and I don't plan 
to use Hungarian notation in my lifetime). That's okay, 
because most of the time the author gives the reasoning 
behind his advice, so you can intelligently decide when to dis¬ 
agree. On the other hand, for most Windows portability top¬ 
ics I think of as important, I was able to find a corresponding 
section in the book. The message crackers in wi ndowsx. h truly 
are the cheapest way to handle the really nonportable mes¬ 
sages, such as WM_COMMAND; the book covers that in detail. Other 
topics I was surprised to find included: how mouse capture 
has changed, how focus/window activation has changed, 
Unicode, the fact that Microsoft's BOOL is not Boolean, the 
importance of using STRICT, how to load a DLL automatically 
into all processes, the change in DLL memory management, 
and much more. I was impressed. 

This book was written in German, and the translator was 
reasonably competent; I think the number of glitches (e.g., 
admonitions to avoid "undocumentated" functions) are about 
equivalent to the number of typos in the average English-lan¬ 
guage book. There are three main flaws in this book. First, the 
prose runs on quite a bit (but it is at least technical run-on, not 
hie humor or self-congratulatory text, as is so often the case 
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in technical books). Second, the book was written before 
Windows 95 was out. This second flaw is the most damaging, 
and is no particular fault of the author's (perhaps the revised 
version of the book is already out in Germany). The third flaw 
is that most of the text implicitly assumes you are using 
Microsoft's compiler. The book is still quite useful for Borland 
programmers, but not quite as useful as it could have been. 
Again, that flaw is partly due to the age of the manuscript 
(Borland is really only now producing a compiler that has 
solid support for NT and Win95), not lack of effort on the part 
of the author. Finally, it is interesting to note that Springer- 
Verlag has achieved the stupidest code disk restriction state¬ 
ment I've ever seen — they insist you agree that they have the 
right to audit your computer for unauthorized copies. That's 
quite a legal load to lay on someone just for buying a book. 
What planet are these publishers living on? 

Despite the lack of strong Windows 95 coverage, I recom¬ 
mend this book to anyone facing a large-scale porting effort to 
Windows 95 or Windows NT. And the average Windows pro¬ 
grammer could do worse than browse this book — it discuss¬ 
es a wide range of Windows-specific programming issues. 
This is one of the meatiest Win32 books I've seen. I hope the 
author produces more books, and that they get translated into 
English more quickly than this one did. If you've got Richter's 
Advanced Windows and are looking for another Win32 book 
that is of better-than-mediocre quality, check this one out. 


Standard C: A Reference 
P.J. Plauger & Jim Brodie 
Prentice Hall, 1996 
248 pages 
$ 29.95 

ISBN 0-13-436411-2 

Most C and C++ programmers don't plan to write non¬ 
portable code, they just fail to write portable code. Some 
Windows programmers mistakenly think portability doesn't 
matter for Windows code, but they are often surprised at what 
breaks when a new version of the compiler comes out, or, 
worse, when they have to switch to a different compiler, or, 
worst, when they have to port to a different Windows plat¬ 
form (e.g., MIPS). It's really not that hard to start making your 
code more portable. All you need is a quick study of the most 
important parts of the ANSI C standard, and an easy way to 
look up documentation for the ANSI C standard runtime 
library functions. That's what this book gives you. 

The first incarnation of this book arrived from Microsoft 
Press in 1989, and it is probably the most thumbed book on 
my desk. I'm not much for memorizing things I can easily 
look up. Is strcmpi () a portable function or a vendor-specific 
function? I reach for Plauger & Brodie. Should I be using 
varargs.h or stdargs.h? I reach for P&B. What's the portable 
way to determine at compile time how big an i nt is? P&B 
comes off the shelf again. Over the years. I've found this book 
gives me the best compromise between conciseness and com¬ 
pleteness. It cannot answer every question about standardized 
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C, but it can very quickly answer my most common questions. 

This latest edition of the book reflects the latest changes in 
ISO/ANSI C. It also includes a disk containing an HTML ver¬ 
sion of the book that you can put on your hard disk and 
browse with your Web browser. I belive this is an innovation 

— it will be interesting to see if it catches on. I will have to start 
using this new edition of the book, but I'm afraid I already 
miss the old edition. It's compact 8" by 5" form seemed to be 
easier to grab, and better able to withstand excessive use than 
the more normal-sized new version of the book. The old edi¬ 
tion's price of $7.95 also inspires nostalgia. Still, there's no 
stopping progress, so out with the old and in with the new. If 
you would like to stop accidentally writing non-portable 
code, this is a good book to have on your desk. 

Let's Talk Books 

Subject: Delphi books 

From: Graham Stratford <graham.stratford@iac-online.com> 
Ron, 

As always, I read the January issue of WDJ cover to cover, 
though much of it went right over my head (also as always). I 
was especially interested in George Tylutki's Delphi review 
(Penrod's Developing Windows Applications Using Delphi), since I'm cur¬ 
rently using Delphi (and delighted with it, I might add). I'll 
add my two cents regarding a book I picked up in December: 
Foundations of Delphi Development for Windows 95, by Tom Swan, pub¬ 
lished by IDG Books Worldwide in September '95. 

First of all, the title is blatantly misleading. This is entirely 
a Windows 3.1 book, with basically a couple of references to 
the W95 toolbar differing from 3.1's icons on the desktop. 
There is NO information about programming Windows 95 at 
all. When he talks about upcoming 32-bit Windows issues 
(two pages), Swan even admits, "I don't have any special 
information about Delphi's 32-bit version, so all of this is pure 
speculation.'' I wonder if the publisher could be sued for mis¬ 
representation. 

That being said. I'm not upset about this deception. When 
I was in the bookstore, looking for Delphi programming 
books for Win 3.1, I ignored the titles and covers, and only 
looked at the contents. Thus it wasn't until I was on the plane 
back to Japan that I noticed the "Windows 95"! 

Since I don't have Windows 95, and probably won't for six 
months or so, I was a bit frantic, but after a brief check inside, 
I confirmed that it was a Windows 3.1 book (what I wanted) 
anyway. Victory from the jaws of defeat! 

Anyway, I'm very happy with this book. There are a lot of 
bonus items included on the CD: a small assortment of the 
usual free/shareware and, more important, a hypertext (using 
MS's Multimedia Viewer) version of the book, and Borland's 
Visual Component Reference! The hypertext book is especial¬ 
ly good, since I can easily use it to yank out bits of source code, 
and also do powerful searches without balancing the book on 
my knees. 

Other good points: 

— Swan puts his Internet address in the Introduction, and 
asks readers to inform him of errors. 

— the book is not loaded with screen shots and padded source 
code listings. I think Swan has shown just enough. 

— there is no introduction to Pascal. I've never used it before 


(though I've used BASIC, C, and C++), and I still trip 
myself up with semicolons and beg i n... end structures, but 
after going through the Delphi manuals I don't need a 
long-winded hand-holding explanation of a FOR loop. 

— each chapter concludes with "projects to try" and "expert 
user tips" that are actually valuable! 

— the final chapter, "Honing Your Delphi Skills," is a grab bag 
of useful tips and techniques, such as creating CRT pro¬ 
grams, using callback functions (though this is explained a 
bit fuzzily), file streams, etc. As Swan says, these short 
items don't fit well into the other chapters, but they are 
well worth learning. 

— an entire chapter is devoted to exceptions, as well as short 
discussions in sample programs throughout the book. 

— treatment of printing, including instructions on how to 
build a print previewer. This was a glaring omission in 
Borland's Delphi docs. 

— a chapter about the clipboard, DDE and OLE (though not 
by any means exhaustive). 

Negatives: 

— database development is limited to data-aware controls 
and a few SQL commands. Definitely inadequate. 

— standard publisher's copyright junk which mentions that 
the disk contents are copyrighted by the authors, but Swan 
does not state what rights he reserves. 

— no discussion of using Delphi for low-level (i.e., C-like) 
programming, without all the visual component stuff. This 
can be done; look at the generic program, in Delphi's 
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3437 335th St. West Des Moines IA 50266, USA 
Phone: (515) 987-2910 Fax: (515) 987-2909 
Internet: rhalevi@hyperact.com 
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http://www.hyperact.com 


□ Request Reader Service #147 j 

Windows Developer’s Journal — Page 67 


April 1996 













































SDK Annotation #109 




DEMOS directory for a 5K "Hello world" kind of program. 
Unfortunately, I have yet to see anyone even mention this. 
— when talking about "slimming down" Delphi applications. 
Swan refers to a program called w81oss.exe, but it is cer¬ 
tainly not part of the standard Delphi installation, as he 
describes. In fact, I can't find it anywhere. 

Anyway, I like the book, and think that it's definitely worth 
the attention of a good reviewer, like Tylutki. Please pass this 
information on to him, if you like. 

Regards, 

Graham in Osaka 

Thanks for this excellent and detailed critique; it's extremely use¬ 
ful to he able to present readers' opinions of books here, not just mine 
and a handful of cronies. 1 hope George will tackle that book in an 
upcoming review and I look forward to seeing what he has to say. 
Thanks! —rib 

To: 70302.2566@compuserve.com 

From: jimmy@meco.easy.net.ph (Jimmy Macasaet) 

Subject: Bad book 

I would like to warn your readers about a bad book — How 
to Create Real-World Applications with Visual Basic, by Ori and 
Nathan Gurewich, $39.99, SAMS. This book is really an 
instruction manual for the included (but crippled) tegomm.vbx 


custom control. Also, no source code is 
included for tegomm.vbx. The graphics 
used in the sample programs are 
absolutely ugly and very amateurish. 
The included sample programs (for 
example, one program displays stick- 
wire drawings of a couple dancing 
while another displays a target which 
you shoot at with your mouse) are 
pathetic. 

Warning! Warning! Warning! Do not 
buy this book! 

If you need a good laugh, take a look 
at it at your local bookstore but don't 
buy it! 


This book has not landed on my desk yet, 
so I cannot respond directly to your com¬ 
ments. However, in the January 1995 
installment of Books in Brief, I reviewed 
Borland C++ Multimedia Programming, by Ori 
and Nathan Gurewich. In that review, I 
noted with disappointment that this 900- 
page book was really about (you guessed it) 
tegomm. vbx, a crippled version of their com¬ 
mercial VBX (available by sending another 
$34.95 to the authors). That book was pub¬ 
lished by Sybex, while the one you mention 
is from SAMS. I assume more reincarna¬ 
tions of this book are to come, unless book 
publishers suddenly get more competence or 
scruples than they currently have. As I said 
in that review, there’s nothing wrong with 
trying to sell a book about a crippled version of your VBX — what's 
wrong is trying to pass off such a book as something it isn't, like a 
more general-purpose programming book. Shame on the authors, 
and shame on the publishers. Thank you for sharing this warning 
with other readers. —rib 

Books Received 

Rex Woollard. Master C++ For Windows. Waite Group Press, 

1995. 406 pages. $34.95 ISBN 1-57169-000-X. 

Bil Lewis, Daniel J. Berg. Threads Primer. Prentice Hall, 1996. 
319 pages. $28.00. ISBN 0-13-443698-9. 

R.J.A. Buhr, R.S. Casselman. Use CASE Maps for Object- 
Oriented Systems. Prentice Hall,1996. 302 pages. $39.00. 
ISBN 0-13-456542-8. 

Randy Otte, Paul Patrick, Mark Roy. Understanding Corba: The 
Common Object Request Broker Architecture. Prentice Hall, 

1996. 202 pages (estimated). $45.00. ISBN 0-13-459884-9. 

John Williams. What Every Software Manager MUST KNOW 
TO SUCCEED With Object Technology. SIGS Books, 1995. 
273 pages. $35.00. SIGS ISBN 1-884842-14-3. PH ISBN 0-13- 
227604-6. 

Microsoft Excel/Visual Basic Reference, 2nd Ed. Microsoft Press, 
1995. 874 pages. $29.95. ISBN 1-55615-920-X. 
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Michael Hat maker, C. Woody Butler, 
David Jung, Ibrahim Malluf, John 
Murphy, Bill Potter. Visual Basic 4 
OLE Database and Controls Super 
Bible. Waite Group Press, 1995. 1067 
pages. $44.95. ISBN 1-57169-007-7. 

John D. Ruley. Networking Windows NT 
3.51, 2nd ed. John Wiley & Sons, 
1995. 665 pages. $32.95. ISBN 0-471- 
12705-1. 

Michael T. Peterson. DCE: A Guide to 
Developing Portable Applications. 
McGraw-Hill, 1995. 568 pages. 
$49.95. ISBN 0-07-911801-1. 

Microsoft Excel/Visual Basic Programmer's 
Guide. Microsoft Press, 1995. 347 
pages. $24.95. ISBN 1-55615-819-X. 

Christopher Watkins, Russell J. Berube 
Jr. Learning Windows Programming 
with Virtual Reality. AP 
Professional,1995. 305 pages. $39.95. 
ISBN 0-12-737842-1. □ 
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RegCreateKey Quicklnfo Overview Group 


<#The RegCreateKey function creates the specified key. If the key 
already exists in the registry, the function opens it. This function is 
provided for compatibility with Windows version 3.1. Win32-based 
applications should use the ReqCreateKevEx function. 


1 


Annotate 


Current annotation 


The documentation for RegCreateKeyO, Reg Create Key ExO. - 
RegOpenKeyO, and RegOpenKeyExO all list several 
predefined handles you can use, such as 
HKEY_CURRENT_USER. However, they fail to document 
the predefined key HKEY_CURRENT_CONFIG, which has a 
structure similar to the registry tree under 
HKEY_LOCAL_MACHINE, but is for storing information 
specific to the current hardware profile. 

Submitted by Paula Tomlinson. 




Save 


Cancel 


delete 


fa>py 

Paste 


j 


fin 


MFC extension class library implements embeddable j, . iqc 
dialog editor / GUI builder. ^ HyperView++ combines Jjlifv*' 
the power of Visual C++ with the ease of Visual Basic! Y 

♦ Embed a custom view / dialog editor' into your application 

♦ Build your GUI visually at run time without recompilation 

♦ Dynamically generate fonns from database on the fly 

O Define your data. Define your GUI objects and controls. 
Connect them together at run time with unlimited flexibility! 
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FREE 
DEMOlJs 


fESgg& HYPERCUBE 

(800) 268-1812 • harlan@hcubc.com " ‘ 

IjSjSJjp http://www.hcube.com/hvwpage.html 
10542 Bradbury Rd, Los Angeles, CA 90064 • (310) 559-2354 


One version 
supports 
Windows 3.1, 
Windows NT and 
Windows 95 


SftTree 1.0 

Tree Control for Windows 


From simple listbox with bitmaps to multi-line, multi- 
column, hierarchical data display, SftTree delivers! 



File Name 

Description 

m 

Size 


i| Project NEWAPP.MAK 




A B-i? 

about, c 

| Easily edit tree data| 

* 


i-Q app.h 

Using any control (combo, edit, .) 


4429 chars 

f S 

i© 

editmdi.c 

Text Edit Window (MDI Child) 

Old MDI edit child window, needs change 

16449 chars 


Ac 

l editmdi h 

Text Edit MDI Child Definitions 

RTF control API 


88129 chars 



Q < windows. h> 

Windows Header File 


151579 chars 


• multiple columns 

• multiple text lines per item 

• drag & drop with auto-scroll 

• single/multiple selection 

• single/multiple roots 

• editable item data 


• columns with titles/buttons 

• resizable columns 

• selectable column alignment 

• sorting 

• standard or 3D look 

• expand/collapse buttons 


/ 

/ 


Supports Windows 3.1, 
Windows NT and Windows 95 

MFC and OWL classes 
included 


/ 

/ 


Use with C, C++ (MFC, OWL) 
and other OLL-call capable 
languages 

Supports AppStudio, 
Resource Workshop and 
SDK dialog editors 


SftTree DLL (with C++classes) $249 
Source Code for SftTree DLL +$100 


VISA/MC/AMEX accepted. 


S&H additional. 

Site licensing available. 


Call today for your free demo! 


Not The Industry Standard 

11 Michigan Ave 
^Wharton, NJ 07885 


(201)366-9618 
FAX (201) 366-3984 
BBS (201)366-3940 
http://www.softelvdm.com^ 
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The Magazine for Windows Programmers 


New Products 

Industry-Related News & Announcements 


Send your press release 
to Miller Freeman, Inc. 
1601 W. 23rd St. 
Suite 200 
Lawrence, KS 66046 


Safe-D Lets You Require Registration of CD Software 


Az-Tech is now shipping Safe-D, a package that helps 
protect software distributed via CD-ROM. Safe-D lets you 
create trial or demo versions of applications that will be dis¬ 
tributed online or via CD-ROM. Once the customers decide 
to purchase the program, they can call you to receive an acti¬ 
vation code that turns the demo version into a fully func¬ 
tional package. Features include verified registration, hard 
disk lock, CPU lock, network lock, date and execution count 


limits, access flags, secure user data, encryption, and serial¬ 
ization. The product includes DLL functions to support a 
custom activation process. Safe-D works with DOS, 
Windows, Windows 95, and Windows NT. 

The Safe-D Professional System costs $495. For more 
information, contact Az-Tech Software, Inc., 201 East 
Franklin, Suite 11, Richmond, MO 64085, (800) 227-0644 or 
(816) 776-2700; fax (816) 776-8398; aztech@tyrell.net. 


fax 913-841-2624 


wdletter@rdpub. com 


Embeddable Basic Upgrade Includes Automated OLE Registration 


Mystic River Software has released Softbridge Basic 
Language (SBL) v3.4, the latest version of their VB-com- 
patible macro language for Windows developers. SBL lets 
developers add scripting capabilities to existing applica¬ 
tions, giving users the ability to customize their applica¬ 
tion using VB-like scripts. This version allows users to 
directly read OLE typei nfo files and automatically gener¬ 
ate SBL classes from them, making application-specific 
OLE classes accessible from SBL. SBL can also directly call 
routines defined by an OLE interface, bypassing the slow¬ 
er IDi spatch interface. Other new features include cooper¬ 


ative registration (SBL can ask your application to register 
methods as it encounters them in scripts, rather than regis¬ 
tering them all up front), direct links to ODBC databases, 
and operator overloading (allowing you to redefine the 
standard operations as applied to classes). 

Softbridge Basic Language v3.4 costs vary, and depend 
on whether you select variable-rate royalties or a single 
fee. For more information, contact Mystic River Software, 
Inc., 125 CambridgePark Dr., Cambridge, MA 02140, (617) 
497-1585; fax (617) 864-7747; 75124.2273@compuserve.com. 


NOVLIB Provides NetWare Access for VB, Delphi, C/C++, and CA-VO 


Blinkmc has released NOVLIB v3.0, a network library 
that supports Visual Basic, Delphi, C/C++, CA-VO, and 
CA-Clipper under W'indows, DOS, and extended DOS. 
The library provides over 450 network functions in cate¬ 
gories such as printing, security, mapping, messaging, and 
accounting. The library is distributed as both a DLL and a 
.lib file, and includes a Windows help file and a 500-page 
manual. 


NOVLIB v3.0 costs $299; upgrades start at $99. For 
more information, contact Blinkinc, 8001 West Broad 
Street, Richmond, VA 23294, (804) 747-3600 (support) or 
(804) 747-6700 (sales); fax (804) 747-4200; 

BBS (804) 747-7333. 
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BoundsChecker Update Integrates With 

Nu-Mega Technologies, Inc. has shipped a service pack 
for BoundsChecker for Windows 95 and BoundsChecker 
for Windows NT, its automatic error detection products. 
This free upgrade integrates BoundsChecker with both 
Microsoft Visual C++ v4.0 Developer Studio and Microsoft 
Visual Test v4.0. Other new features include the ability to 
launch multiple instances of BoundsChecker for detecting 
errors in OLE-based applications. 


DFL Ships Graphing VCL for Delphi 

Light Lib Business is a new VCL that lets Delphi pro¬ 
grammers add dynamic graphing capabilities to their 
applications. The product integrates with the Delphi IDE, 
allowing Delphi programmers to add graphs without writ¬ 
ing any code. End users can change all attributes of a 
graph (columns in view, graph type, etc.) and save the 
graph as a BLOB (binary large object) for later retrieval. 


Test 

BoundsChecker Professional Edition v3.01 is regularly 
priced at $999, but is available for a limited time for $499. 
BoundsChecker Standard Edition v3.01 costs $299. For 
more information, contact Nu-Mega Technologies, Inc., 
P.O. Box 7780, Nashua, NH 03060-7780, (603) 889-2386; 
fax (603) 889-1135; info@numega.com; 
http:llwww.numega.com. 


Light Lib Business costs $199 for the OCX-only edition, 
$249 for the Standard Edition, or $449 for the Professional 
Edition. For more information, contact DFL Software, Inc., 
55 Eglinton Avenue East, Suite 208, Toronto, ON, 
CANADA M4P1G8, (416) 487-2660; fax (416) 487-3656; 
BBS: (416) 487-4041; CompuServe: GO DFLSW; 
http:llwww.dfl.com. 


I-MODE CD-ROM Includes Magazine Text, Source Code 


Developer Source is a new subscription-based CD- 
ROM that provides indexed access to publications of inter¬ 
est to programmers. The CD covers up to three years of 
back issues of 30 magazines, including Dr. Dobb's Journal, 
Windows Developer's Journal, Byte Magazine, Microsoft 
Systems Journal, and IEEE Software. The package includes 
more than 1,000,000 lines of published code available for 


Graphic Library Now Supports Win95 

Scientific Endeavors Corporation has ported their C 
graphics library. Graphic, to Windows 95. Users of the 
library can continue to write programs that look like DOS 
programs and allow Graphic to handle the GUI program¬ 
ming. The library architecture has changed to make it easi¬ 
er for users to create and manage their own windows. The 


copying and pasting into other applications. A one-year 
subscription includes four quarterly updates on CD-ROM. 

The annual subscription to Developer Source is $545 
for single users and $2,495 for the five-user network ver¬ 
sion. For more information, contact I-MODE Publications, 
Inc., 100 Corporate Drive, Yonkers, NY 10701, 

(914) 968-7008; fax (914) 968-9340. 


GraphiC/Win screen driver is in a DLL and the entire 
Graphic library can now be created as a DLL. 

Graphic for Windows 95 costs $495. For more informa¬ 
tion, contact Scientific Endeavors Corporation, 

508 North Kentucky St., Kingston, TN 37763, 

(615) 376-4146; fax (615) 376-1571. 
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File System Library Adds Hypertext Link Support 


Menai Corporation has updated their Gamelon v2.0 file 
I/O library to support hyperlinks across multimedia files. 
Gamelon is a file I/O library that simplifies creating, writ¬ 
ing, and reading structured data files. Gamelon is avail¬ 
able for Windows 3.1, Windows 95, Windows NT, OS/2 
2.x, OS/2 3.0, OS/2 Warp, and Sun's Solaris, and it sup¬ 
ports C, C++, and Visual Basic. All Gamelon libraries sup¬ 
port Unicode. Other features include object nesting, cross- 
referencing, indexing, transaction management, automatic 


Image Format Library Ships as OCX 

AccuSoft has released AccuSoft Image Format Library 
v5.0 as an OCX for Windows 95, making it easy to access 
from Visual Basic v4.0 and Visual FoxPro for Windows 95. 
The OCX32 Image Format Library v5.0 lets developers 
import, display, rotate, zoom, compress, scale to grey, and 
print graphics images. The library supports 36 file formats. 


object tracking, and platform-independent, type-safe data 
storage. 

Gamelon costs $395 for Windows 3.1 (a free interface 
file for Delphi programmers is also available); $495 for 
Windows 95, Windows NT, and OS/2 Warp; $1195 for 
Solaris, Sparc, and x86; and $129 for Visual Basic VBX. For 
more information, contact Menai Corporation, 

1010 El Camino Real, Suite 370, Menlo Park, CA 94025-4335, 
(415) 853-6450; fax (415) 853-6453; BBS (415) 617-5726; 
info@menai.com; http://www.menai.com. 


including TIFF, JPEG, Photo CD, Photoshop, MacPaint, 
PCX, BMP, Windows ICO, and more. 

The OCX32 Image Format Library v5.0 costs $795, or 
$1,995 for OCX32 Pro Gold. For more information, contact 
AccuSoft, Tivo Westborough Business Park, Westborougli, 
MA 01581, (508) 898-2770; fax (508) 898-9662. 
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New MFC Class Provides Dialog Editing 

HyperView++ vl.O for MFC is a new class library that 
lets your application view and edit dialogs. The library 
provides a class called CHyperView (based on MFC's CView) 
that operates like an enhanced CFormVi ew, and allows you 
to edit, create, and use dialogs and views without recom¬ 
piling. The package comes with a base set of objects and 
controls, but you can create custom objects and controls to 
use in the editor. The package includes C++ source code, is 


compatible with 16- and 32-bit Windows, and is DBCS- 
compatible. A demo is available at 
ftp://ftp.hcube.com/hcube/hvwdemo.zip, or on 
CompuServe at GO MSMFC (download hvwdemo.zip). 

HyperView++ vl.O costs $2,000 per project. For more 
information, contact Hypercube, Inc., 10542 Bradbury Rd., 
Los Angeles, CA 90064, (310) 559-2354; fax (310) 559-2357. 


WinAPI Oblets Encapsulate Windows API 


Sheridan Software Systems, Inc. is shipping WinAPI 
Oblets, an encapsulation of the Windows API implement¬ 
ed as browsable OLE objects. WinAPI Oblets provide a 
structured interface to the Windows API and transform 
Windows callback functions into OLE events, making 
them accessible to environments (such as Visual Basic) that 
cannot directly provide callback functions. WinAPI Oblets 
expose a type library that describes all its objects, meth¬ 


ods, and properties. 

WinAPI Oblets costs $139 and is included with 
Sheridan's ClassAssist for VB 4.0, which costs $249. For 
more information, contact Sheridan Software Systems, 
Inc., 35 Pinelaivn Rd., Suite 206E, Melville, NY 11747, 
(516) 753-0985; fax (516) 753-3661; BBS (516) 753-5452; 
CompuServe: GO SHERIDAN; http://www.shersoft.com. 


Win95Pak Brings UNIX Tools to Windows 95 


Win95Pak is a new package of classic UNIX tools for 
Windows 95 and Windows NT. The package includes 
more than 100 applications, such as emacs, bash, sed, awk, 
vi, and perl . The package also has Windows connectivity 
software for Sun Solaris, Digitial UNIX, HP-UX, and 
SunOS. 


The Win95Pak CD-ROM costs $80. For more informa¬ 
tion, contact Ready-to-Run Software, Inc., 4 Pleasant St., 
P.O. Box 2038, Forge Village, MA 01886-5038, 

(508) 692-9922; fax (508) 692-9990; info@rtr.com; 
http://www.rtr.com. 


Updated Source Editor Provides Dynamic Context Info 


Source Dynamics, Inc. is shipping Source Insight v2.0, 
the latest version of its C/C++ programmer's editor for 
Windows 95 and Windows NT. Source Insight handles 
even large source code projects and provides up-to-date 
symbol browsing without compiling. A local symbol win¬ 
dow lets users see what other functions or symbols are in 
the current file. Project-wide search and replace and 
rename makes it easy to rename identifiers across many 
files. 

New features in this release include a dynamic source 
context window that shows global and local contextual 


information as users type or click on symbols, a dynamic 
"clips" window that lets users rearrange code and user 
boilerplate source code efficiently, and support for Win95 
and NT features, such as long file names, UNC names, the 
registry, 16x16 icons, drag-and-drop editing, toolbars, and 
context menus. 

Source Insight v2.0 costs $249.95. For more informa¬ 
tion, contact Source Dynamics Inc., 22525 SE 64th Place, 
Suite 260, Issaquah, WA 98027, (206) 557-3630; 
fax (206) 557-3631. 


Premia Ships Win95 Version of Codewright 


Premia has revised its programmer's editor, 
Codewirght Professional, to give it a new user interface 
and compatibility with Windows 95. A new API Assistant 
helps programmers code API calls by checking that the 
right number and type of parameters are included. 
Another new feature is Button Links, graphical buttons 
programmers can place in source code and other text files. 
The buttons do not interfere with compiling and allow 
programmers to link to non-text documents such as dia¬ 


grams and word processor documents. A "To Do" button 
lets programmers make notes in the code about work yet 
to be done. Other types of buttons run applications or 
shortcut macros. 

Codewright Professional costs $269; upgrades are $79. 
For more information, contact Premia Corporation, 

1075 NW Murray Blvd., P.O. Box 268, Portland, OR 97229, 
(503) 641-6000; fax (503) 641-6001; info@premia.com; 
http://www.premia.com. 
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X-Designer Available for Alpha OpenVMS 


Imperial Software Technology has released X-Designer 
for the DEC Alpha running OpenVMS. X-Designer is a 
cross-platform GUI builder that generates MFC code for 
PCs running Windows and Motif code for UNIX systems. 
The product supports all major V'MS and UNIX systems. 


Dunn Releases Secure SQLBase 

Dunn Systems Secure SQLBase is an enhanced version 
of Gupta's SQLBase that provides secure client/server 
facilities. Programmers can use 4GLs such as 
SQLWindows, Delphi, Visual Basic, PowerBuilder, and 
C++ to create applications that use the Internet as a secure 
wide-area network. The company licensed RSA Data 
Security's public key encryption code and integrated that 
as the communications layer for Gupta's SQLBase data¬ 
base engine. The software is compliant with Netscape 


X-Designer v4.0 costs $3,500, which includes one year 
of free support and upgrades. For more information, con¬ 
tact Imperial Software Technology, 120 Hawthorne Ave., 
Suite 101, Palo Alto, CA 94301, (415) 688-0200; fax (415) 
688-1054; http://www.ist.co.uk; sales@ist.co.uk. 


Communications' proposed Secure Socket Layer (SSL) 
standard. 

Dunn Systems Secure SQLBase prices start at $1595 for 
a five-user version, which includes a copy of Gupta's 
SQLBase. For more information, contact Dunn Systems, 
Inc., 4301 West Touhy Ave., Lincolnwood, IL 60646, (800) 
486-3866; (708) 673-0900; fax (708) 673-0904; 
http://wivw.dunnsys.com; securesales@dunnsys.com. 


4D Database SDK Available for Windows 95 


ACI has released a new version of 4th Dimension 
Software Development Kit. The package bundles ACI's 4th 
Dimension, 4D Compiler Pro, 4D Insider, and an unlimited 
runtime distribution license. 4th Dimension is a 32-bit, 
cross-platform, relational database with a graphical inter¬ 
face and a built-in programming language. 4D Compiler 
Pro is a machine code compiler that generates code for 
both Windows and Macintosh. With this version, develop¬ 
ers need only compile code once to generate databases for 
both platforms. 4D Insider is a code browser and graphical 
cross-reference tool that provides a complete structural 


dictionary of 4th Dimension databases. The new version 
lets developers search for database objects by date to 
ensure they are using the most current version. 4D Engine 
provides the tools needed to build, compile, and distribute 
4D databases. Developers merge their compiled 4D data¬ 
bases with 4D Engine to produce a standalone, executable 
application. The 4D SDK costs $2,995. For more informa¬ 
tion, contact ACI US, Inc., 20883 Stevens Creek Blvd., 
Cupertino, CA 95014, (800) 881-3466; (408) 252-4444; 
fax (408) 252-4829; AppleLink D4444. 


BLINKER 4.0 Produces Compressed EXEs and DLLs 


Blinker v4.0 is the latest version of Blinki/ic's linker for 
Windows, DOS, and extended DOS programs. This ver¬ 
sion allows users to produce compressed executables that 
execute directly with no separate decompression step. The 
compressed executable can reduce distribution costs, 
reduce network traffic, and discourage decompilation. 

This version also provides fast linking of 32-bit PE format 
executables for Windows NT and Windows 95 and is com¬ 


SSI Ships Embedded Development Tools 

Systems & Software, Inc. has updated their line of tools 
for embedded application development. Link&Locate 386 
v2.1 is the latest version of their linker/locator/builder for 
embedded x86 development using C/C++. This version 
features a visual command file builder (WinLink 386) and 
is compatible with Borland C/C++ v4.5, as well as WAT- 
COM and Borland assemblers. WinLink 386 provides a 
Windows user interface to SSI's existing line of 32-bit link¬ 
ers (Link&Locate 386 and SP/Link 386) and integrates 


patible with C, C++, Microsoft FORTRAN, Pascal, CA- 
Clipper, and assembler. Blinker v4.0 is also a royalty-free 
DOS extender that can create and use DLLs in extended 
DOS programs. 

Blinker v4.0 costs $299; upgrades start at $99. For more 
information, contact Blinkinc, 8001 West Broad St., 
Richmond, VA 23294, (804) 747-3600 (support) or 
(804) 747-6700 (sales); fax (804) 747-4200; 

BBS (804) 747-7333. 


them with the SoftProbe for Windows debugger. SoftProbe 
for Windows Remote Debugger is a new Windows-hosted, 
graphical, source-level debugger that lets you download a 
program from the host PC and debug on the target system. 

Link&Locate 386 v2.1 costs $895. SoftProbe for 
Windows Remote Debugger costs $1,995. For more infor¬ 
mation, contact Systems & Software, Inc., 18012 Cowan Ave., 
Suite 100, Irvine, CA 92714, (714) 833-1700; 
fax (714) 833-1900; info@syssoft.com. 
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Readers' Forum 


Send letters to wdletter@rdpub.com. 


Dear Ron Burk, 

I'm writing with regard to some¬ 
thing which I hope is not going to be a 
continuing trend, namely the lack of 
executable files on the code disk. After 
reading Ton Plooy's article "A DLL 
Load Monitor" in the November issue, I 
thought that this would be a very useful 
utility, which would help me to reclaim 
some lost disk space, hopefully without 
Windows crashing in the process. I was, 
therefore, a little dismayed to discover, 
upon unzipping the relevant file from 
the code disk, that it only contained 
source code, without any executable 
files. 

I do Windows and C programming 
for fun, using Borland's Turbo C for 
Windows Visual Edition. It's not a cut¬ 
ting-edge compiler, but it's good 
enough for me. I am now in a situation 
where I can do 1 of 3 things : 

• Give up on using this utility. 

• Try to compile it in Turbo C, hoping 
that it doesn't use any non-support- 
ed calls (or if it does, that my limited 
knowledge will let me work around 
it). 

• Buy one of the professional compil¬ 
ers that will deal with the code. 

As an occasional programmer, I really 
cannot justify paying out $400 - $500 
dollars on a cutting-edge compiler, 
plus an unknown amount to upgrade 
my hardware to run it. 

I read WDJ because I respect and 
appreciate the professionals who write 
the articles and will share their time and 
experience, not because I'm a profes¬ 
sional and I want to see how other pro¬ 
fessionals do it. I would like to think 
that your former subtitle, "Advanced, 
Serious, Technical," relates to the arti¬ 
cles published, not to the target audi¬ 
ence. 

My plea to you is not to forget "the 
little guy." I'm sure I'm not the only per¬ 
son who buys WD/ but doesn't have the 
latest software (and cannot afford to get 
it). I admit that I did not unzip every file 
on the code disk to see if it contained an 


executable file, and I may just have been 
unlucky that Ton did not provide one, 
but I would like to appeal to your 
authors to provide executables as well 
as source code, if at all possible. I would 
hate to think that the audience of WDJ 
will eventually be split into those who 
have the latest technology (and get the 
best information) and those who don't 
(and have to stand outside, looking in 
and watching the rich kids play). 

I would be interested to read your 
thoughts on this matter and on the 
future direction of WDJ. 

Yours sincerely, 

Nigel Hooper 

Because we make an effort to make the 
code in the magazine vendor-independent, 
you shoidd not have much trouble compil¬ 
ing it with Turbo C. For example, the code 
in that particular article was compiled with 
Visual C++, Symantec C++, and Borland 
C++. I guess I'm assuming that when code 
compiles with Borland C++, the odds are 
very good that it compiles with Turbo 
C/C++. If that's not the case, readers should 
let me know. 

But your main point is about including 
executables. This has always been a 
damned-whether-you-do-or-don't situation 
for us. There seem to be as many readers 
who want as few executables as possible (to 
minimize download times) as there are who 
want all possible executables (to minimize 
hassles after downloading). My response 
has been to pick and choose which articles 
we include binaries with. That's worked 
pretty well, but on this particular article 1 
completely fell asleep at the wheel. This arti¬ 
cle is clearly a case where the executables 
have value quite apart from the source code, 
and I simply forgot to stick the binaries on 
the code disk. I have incorporated the bug 
fixes mentioned in the previous letters and 
we have uploaded a revised code disk to 
CompuServe (forum SDFORUM, Library 
7 "R&D Publications") and to our FTP site 
at ftp.mfi.com (in pub/windev). Thanks 
for waking me up! —rib 


Good evening. 

In your October 1995 issue, the arti¬ 
cle "Understanding NT: Processor 
Portability" was extremely useful to my 
company. I heard through various chan¬ 
nels that NT everywhere was supposed 


to be compatible everywhere. I tried 
running our 32-bit NT/Intel versions of 
our product MATHEMATICS DLL 
TOOLKIT!™ Version 2.2 on my 
PowerPC. Nothing happened. I tried 
running our 16-bit WFW/Intel versions 
on our PowerPC. Nothing happened. 
Then along comes Paula's article. I 
checked the optimizations on our C ver¬ 
sions (compiled in Microsoft Visual 
C++ 1.5) and our Delphi versions. My C 
versions were optimized for 386 chips. 
My Delphi versions were already capa¬ 
ble of running on 286 chips. I recom¬ 
piled my C versions for 286 chips. Both 
my C and Delphi versions worked fine 
on my PowerPC under NT! I also suc¬ 
cessfully ran my C versions on an Alpha 
under NT. 

Thanks for the tip! Keep the NT arti¬ 
cles coming! 

John A. Jackson 
President & CEO 
LWE Research, Inc. 
P.S. The emulator is not THAT slow! 

Even though I edited that column, it was 
only when I got your letter that I really 
grasped how neat this is. Accordingly, when 
I built anntater.exe, our automatic help 
file annotater, I avoided using 80386 
instructions and was gratified to see it run 
successfidly under NT on a Power PC. 
There's still a good reason to have an up-to- 
date 16-bit Windows compiler, I think, 
though the Visual C++ team seems to dis¬ 
agree. Thanks for the note. —rib 


From: Alexander C Lindsey 
<lex@halcyon.com> 

Subject: WDJ 1/96 issue 

To: 70302.2566@compuserve.com 

Although I usually enjoy reading 
WDJ, the January 1996 issue blows me 
away with its excellence. I receive some¬ 
thing like 20 subscriptions, few of 
which match the information content of 
your magazine. 

In particular, the articles on dialog 
boxes — WM_N0TIFY and dialog units — 
provided insight that I have lacked (I, 
too have wandered through life not 
truly understanding dialog units!). 
WinExecExO solves some real problems 
and also provides good insight. 

Finally, your book reviews are a joy 
to read. I am truly glad that someone 
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out there has intellectual standards and 
is not afraid to exercise them. If I read 
one more book in which "powerful", 
"advanced" and "cool" constitute 80 
percent of the author's critical vocabu¬ 
lary, I may go postal. 

Suggestion: the books and documen¬ 
tation available for OLE generally set a 
new, and sorry, mark for confusion, 
obscurity, and incompleteness, even 
given the not-so-great standard of exist¬ 
ing Windows documentation. I am cur¬ 
rently trying to develop some OCX con¬ 
trols to work with Visual FoxPro, and 
finding amazing gaps in the available 
information, as well as bizarre behavior 
from controls which are really quite sim¬ 
ple — mostly MFC with a couple of 
member functions written by me (exam¬ 


ple: when I comment out my OnDrawf) 
function, a subclassed scrollbar still 
draws itself!?!@#?). 

Anyhow, I want to encourage future 
concentration on OLE. the situation 
almost makes me pine for the good old 
days of IBM GCxx manuals (the ones 
with "This page intentionally left blank" 
— a self-referential logical conundrum 
worthy of Epimenides — on every other 
page). They were a model of clarity and 
to-the-point writing compared to the 
current mess. 

I have been beating my head against OLE 
for a while now, but still have not gotten to 
the point where I would be comfortable 
reviewing all the OLE books on my shelf. On 
the other hand, I am competent enough now 


to at least point out the ones that are little 
more than instructions on how to press 
"wizard" buttons. I'll try to get some OLE 
books covered in upcoming issues. Thanks 
for the compliments! —rib 


From: "Peck, Jon K." <peck@spss.com> 
To: "'70302.2566@compuserve.com'" 
Subject: All about Dialog Units 

Having just read through your article 
on this long mysterious subject, and 
having grappled with this problem 
myself over the years, I have a few com¬ 
ments. It is amazing that such a heavily 
used coordinate system is so mysteri¬ 
ous. 

We struggled with this problem in 
writing a tool that can check dialog 



Developer's 

Marketplace™ 


C and C++ DOCUMENTATION 


!! VERSION 6.0!! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, cross-ref, file/function index. 

• C-CMT ($69) Creates/inserts/updates comment- 
blocks for each function, listing the functions 
and identifiers used by it. 

• C-METRIC ($59) Counts path complexity, counts 
comments, code, ’C’ statements. 

• C-LIST ($69) Lists and action-diagrams, or 
reformats into standard formats. 

• C-REF ($69) Creates cross-reference of local/ 
global/define/parameter identifiers. 

• C-DOC ($199) Package All 5 programs integrated 
as DOS program. <10,000 lines. 

V6.0 C-BR0WSE Windows graphic-tree viewer. 

• C-DOC Professional ($299) DOS, Windows, OS/2. 
3-ring binder/case. <1,000,000 lines. 

30-DAY Money-back guarantee. CALL NOW! 

SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Mississauga Voice/Fax (905) 858-4466 
0NT Canada L5N-4M1 http://swbs.idirect.com 


Please see Ad Index for our larger ad. 
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Warnier/Orr Diagramming 

with 

B-liner 

(bracket outliner) 


Divide and conquer. Manage complexity by visually 
breaking down problems using B-liner, a new 
Warnier/Orr diagram editor. Uses range from rigorous 
process specifications and structured data diagrams 
to work breakdowns and informal “to-do" lists. It is 
an hierarchical editor where brackets enclose 
decompositions. You are not locked into any particular 
technique or methodology. 


B-liner provides an environment where you focus on your 
analysis or design instead of the formatting chores. 
B-liner diagrams are elegant, simple, and easy to 
understand. Perfect for communicating your analyses, 
designs, and estimates to your clients. 

Features include: • Powerful editing & formatting 
• OLE 2.0 server • Drag & drop • Extensive online help 


B-liner can be used alone or within OLE 2.0 applications 
like Word. Runs on Win 95, Win 3.1, & NT. 


Limited Time: $149 


VISA/MC/PO/Check 


60 Day Money Back Guarantee 


(508) 685-7003 
I For free demo & info: http://www.std.com/varatek 
I Vaiatek Software. Inc. #264.733 Turnpike. No. Ardour, MA 01845 
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Report woes? 

Slow, large, impossible? 


PrintForm 

Create complex, impossible reports. 

High quality documents, very well suited 
for form letters, reports and tables. Icons, 
bitmaps, texts. Fonts, word-wrapping, ali¬ 
gnment, headers, footers, numbering. DLL 
and C++ API. Demos in CompuServe: 
MSMFC or MSB ASIC 

DLL and source versions, 16- and 32-bit. 
30 day money-back guarantee. 

KWG Software: CIS: 100010,204, Tel: +49-531-72982 
Fax: +49-531-74501, pfo@kwgsoft.s-link.de 
European Software Connection: 800-986-6578, 913- 
832-2070, Fax: 913 832-8787, CIS: 71141,3624 

□ Request Reader Service #151 n 



The Revolutionary Guide To 

DELPHI 32 

• Covers the advanced 
features of the Delphi 
language 

• Written by 6 leading 
Delphi developers 

• Providing in-depth in¬ 
formation on the Win95 API, Delphi tools 
API, inline assembly language and more 

Long et al ISBN 1-874416-67-2 $44.95 


How To Order 


Phone. 800 937 5557 

Fax.800 PRI ORDER 


VISA MASTERCARD AMEX DISCOVER 
Quote code CL48 for free freight 

For more information or a free catalog 
of Wrox Press programming titles call 
800 USE WROX 



• Visit Wrox Press Developers' Reference 
on the Web, for more details 


http 


://www .wrox.com/ 
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Developer Jobs! 

Internet: ngi@scientific.com 

Commercial software developers should con¬ 
sider registering with Scientific Placement. 
R&D jobs for software engineers, SQA, prod¬ 
uct managers, etc. Nationwide contacts with 
both large and small companies including 
start-ups. Many clients develop commercial 
software products. Most develop for Win¬ 
dows, NT, Macintosh, OS/2, and Unix based 
platforms. We also recruit in other leading 
edge technology areas such as PDA, low level 
and real-time, compilers, etc. Managed by 
graduate engineers. Send resumd or call for a 
marketability assessment. Never a fee. 

Scientific Placement, Inc. 
800-231-5920 Fax 800-757-9003 
http://www.scientific.com 

CompuServe:? 1250,3001 AOL:davesmall 
SPI8, Box 19949, Houston. TX 77224 
713-490+100 Fax: 713-4964)373 
SPI8, Box 71, San Ramon, CA 94583 
510-733-6168 Beth@spica.Mt.coro 
SPI8. Kenmore Station, Box 15225 
Boston. MA 02215 617-42+8372 jen@spbos.pn.com 
SP18, P. O. Box 202676. Austin. TX 78720-2676 
V 512-260-0123 lej@zilker.net _ 
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boxes automatically to see if there is any 
clipped text in controls. Our main sys¬ 
tem has 500 dialog boxes, and we local¬ 
ize it into seven languages, so that's a lot 
of stuff to look at manually! We labored 
a while to get the formula right, since 
there are many different possible aver¬ 
ages of character widths that could be 
used, including the length of a-zA-Z, 
length of the entire printable set, the 
AveC harWi dth coming out of Fontmetrics, 
and others. We found that, somewhat 
surprisingly, the average of a-zA-Z 
rounded up to the next integer actually 
works. MS claims that they use this for¬ 
mula even in single- and double-byte 
parts of the world where this doesn't 
seem to be the best set of characters to 
average over. 


One other wrinkle can cause trouble 
if you are trying to decide whether text 
fits in a control: you have to allow for 
the size of the graphic elements of that 
control, for example, the size of a radio 
button or 3-D border. We thought initial¬ 
ly that these could also be defined in 
DBUs, but it turns out that those ele¬ 
ments have the same absolute size in 
pixels in all fonts. This means that as 
you vary the point size, the graphical 
elements do not change corresponding¬ 
ly. At uncommon point sizes things can 
look pretty silly. 

It is also an interesting mystery to fig¬ 
ure out how the system font is really 
defined, since, at least in Windows 3.1, it 
can be redefined in the wi n. i ni file. It is 
another interesting mystery to think 


about what happens to national charac¬ 
ters not in code page 1252 when you use 
MS Sans Serif. 

Regards, 

Kim Peck 
SPSS Inc 

Wow, it sounds like you've become more 
expert in dialog box units than I ever hope to 
be! Thanks for the additional technical tid¬ 
bits. —rib 


From: Vicente Alcalde <ajig@max> 

To: 70302.2566@compuserve.com 
Subject: Extern/extern 
Hi Ron, 

In the December 1995 issue of WDJ, 
"Books in Brief," you were reviewing 
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•WinEdit 96- 


$99.95 WinEdit 96 for Windows 95 and 
Windows NT (Intel, MIPS, Alpha, 
PowerPC) has a 447-function Windows 
macro language, 5 MB file handling, 
compile automation for most languages, 
and automatic text coloring. 

It's for C++ and other languages. Demos 
are free for the download! Or buy under 
our 90 day, money back guarantee. 

• For your free, eve! copy: 

Web: http://www.windowware.com 
FTP:ftp.windowware.com 
CompuServe: WINAPA, Sec. 15 
BBS: 206-935-5198 
Orders: 1-800-938-4599 
or via our secure Web server 
Wilson WindowWare, inc. 
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• Barcode recognition + insert 

• Noise removal 

• Skew correction 

• Line removal 

• Tiff r/w - de /compress - scale 

Axtel, Inc. 

18255 Ml. Baldy Circle 
Fountain Valley, CA 92708 
Tel: (714)964-6666 
Fax:(714)964-6766 
_ CompuServe: 75270,2412 


Free demo on hitp://www.axtel.com 
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Windows NT Drivers 


Development 

Consulting 

Training 

by the best in the industry 

• File Systems • Kernel Mode Drivers 

• NDIS Drivers • Systems Internals 



Open Systems Resources, Inc. 

105 Route 101 A, Suite 19 

Amherst, NH 03031 

(603) 595-6500 — info@osr.com 


Call or email for a free no obligation quarterly subscription to 
The NT Insider , the world’s only newsletter dedicated entirely 
to Windows NT systems software development! 
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CDROMs! 


Official Slackware™ Linux - Slackware 3.0 (ELF) Linux, by author of 
Slackware. Easy install: learn Unix. XFree86 3.1.2, Td/Tk, GCC 
(2.7.0) compiler, Doom™. Works on 98% of PC's. 2 discs. $39.95 
Slackware subscription - convenient 3 month updates. $24.95 
FreeBSD® 2.1 - Berkeley BSD for PC. Solid Unix®-like, src, XFree86 
3.1.1, dev. tools, etc. (Subscription every 6 mo. $24.95) $39.95 
CUG Library - 10 years C/C++ Users'Journal src, listings. $49.95 

CICA® MS Windows - 5000 up-to-date shareware. 2 CDs. $29.95' 
Hobbes OS/2 Archived - 1000MB OS/2 apps, drivers. $29.95' 
Blackhawk 95 - 200 MB great Windows 95 applications. $29.95' 
Newt for NT - Windows NT app's, src, utils, GNU, drivers. $39.95' 
Simtel® MSDOS - Two disc set, classic MSDOS shareware. $29.95' 
Science Library - Technical, engineering shareware + book. $39.95' 
Perl - Source, binaries for many systems, documents. $39.95 
Math Solutions - Math programs, source code, docs. $39.95' 
POV-Ray - 3-D Raytracing: 1000 wow! images, src/binaries. $39.95 

‘Shareware programs require separate payment to authors if found useful 

— Authors wanted. Please email discdev@cdrom.com — 


ORDER NOW! 1-800-786-9907 


Shipping is $5 in USA/Canada/Mexico, $9 Overseas per order 




'9 
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Walnut Creek CDROM 

Suite D-*93, 4041 Pike Lane, Concord CA 94520 
Phone: +1-510*740783 • FAX: +1-510*740821 • email:orders@cdrom.com 
All of our CDROMs are 100% unconditionally guaranteed! 

Call today for your free catalog of all our CDROM titles! i-1 

See these products free at http://www.cdrom.com/ Adcode: 693 
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H Lexicus Longhand 

P K O F S S 1 O N A L 

Handwriting Recognition Software 

Software Developer Kit (SDK) 

Use our new SDK for high user acceptance of 
your pen applications. Lexicus Longhand 
provides a fast and natural method of data 
input. With our SDK, the creation and 
prototyping of your pen-based applications has 
never been easier. The SDK includes: 

- Dictionary Building Tools 
- Custom VBX Controls 
- Documentation 
- Code Samples 

1-800-LEXICUS 

415-462-6800 

http://www.lexicus.mot.com 

MOTOROLA 

Lexicus Division 
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Employment Service 


SALARIED SOFTWARE 
DEVELOPMENT AND 
SUPPORT ENGINEERS 


Clients and affiliates nationally... 
Clients pay our fees (always), and 
your Interview and relocation 
expenses (usually). 

RSVP SERVICES 

trusted by computer professionals 
since 1966 


Ref: WDDJ 

PO Box 8369 Cherry Hill NJ 08002-0369 
Voice: 800/222-0153 
Fax: 609/667-2606 
Internet: npa1621@connectinc.com 


mail/fax/email resume J 
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NuGraf® Developer's 3D Toolkit 


NuGraf is a complete drop-in solution for de¬ 
velopers seeking to integrate advanced 3D ren¬ 
dering technology into a new or existing CAD, 
modeling or visualization application. 

Features a mature, robust 
and proven photo-realis¬ 
tic Tenderer of impeccable 
quality and speed, a hier¬ 
archical database man¬ 
ager, a wide selection of 
3D modeling primitives 
(mesh, patch, NURBs), a 
hierarchical picking 
mechanism and a programmable output driver 
subsystem. Multi-platform: PC (DOS. Windows 
3.1/95/NT, Watcom) & UNIX. See WEB site for 
information, online API, demos and image gal¬ 
lery. $995 and $3500. M/C, VISA. 


OkiflO 6271 Dorman Road, Unit#6 

Computer Mississauga, Ontario, L4V 1H1 

Graphics, Inc. T: < 905 > 672 - 9328 , f:072-2700 

Email: sales@okino.com, WEB: http://www.okino.com 
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Switch 

While 

For 

Do-While 


-If you know C or C++, you already 'Makes modifications easy - 
know how to uaa Vlsua1Coder++! change a function & all 
•Speed development by dragging references to it are updated 
& dropping, or press a single key automatically 
•Eliminates syntax errors - most -Reduces your workload - type 
braces, parenthesis, 5 semi-colons In variables, functions & classes 
are generated automatically - VlsualCpder++ automatical! 


fhey’re always Just a click away 
even filtered for the appropriate 
context 

•Never type a name twice - 
function prototypes & include 
statements are generated 
automatically 


declares them, inferring the da 1 
type from their usage 
•Integrates with most C/C++ 
environments 
•Generates beautifully 
formatted C/C++ code 
•Produce applications for 
Windows 95. Windows 3.1, 
Windows NT, and OS/2 Warp 


THE REMARKABLE NEW C/C++ CODE PROCESSOR 


VisUAlCodER++™ 

pnpn lor Wrtdows 

□ EMAIL centauris@aol.com 
So FAX 1-619-630-8054 
Kip&l Centauri Software 

4140 OcaanikM Bin) HS8-103 Oc—nmd«, CA 82066^ 


To Order or for* 
FREE information 

1-800-577-0556^ 

_ ext. 410^. 

•Plus $10 ssh. foreign add $20 
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Demo / Tutorial / CBT / Presentation 


Visual Windows Automation 
Multimedia Authoring Development Kit 

G Use ShowBasic Recorder to generate the editable, 
mouse/keyboard simulation code invariant to window’s 
size and position, screen resolution and video driver. 

G Achieve visual control over external applications 
and unlimited flexibility by programming in full 
featured Basic extended with the unique presentation 
and CBT related functionality, use even access to 
external DLLs and Windows™ 16-bit or 32-bit API. 

G Pack your application in a compressed executable 
with the small self-installed run-time and all supporting 
files (BMP. WMF, WAV, MIDI. AVI), compatible with 
Windows 3.1, Windows 95 and Windows NT . 

G Deliver your titles transparently via WWW - 
ShowBasic can be integrated with any WEB browser. 

Development license $299 with 30 day money back guarantee. Royalty free license $895. 

If you don't need all the power of ShowBasic - use our simple, 

vet flexible scripting language for live demos and automation: 

Single-user license $30 ($60 Pro). Royalty free license $300 ($500 Pro) Visa/MC accepted. 

Find more information, demos, samples and evaluation copy: 

http://www.cnj.digex.net/~mik 

■ MIKSoft, Inc. tel/fax: 908-390-8986 

37 Landsdowne Road. East Brunswick NJ, 08816 
Interne!: mik@cnj.digex.nel CompuServe: 74127.3671 
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The MFC Windows Control Construction Kit 
A Programmers Resource 

By Jack Tackett, Jr. and Keith E. Bugg 

Book includes a disk! 

Learn HowTo: 

□ Create owner draw controls with 
bitmaps. 

□ Display, but disable, list box items. 

□ Subclass controls, simplified at last 
Use the new Windows 95 

controls, including: 

Q Tabbed dialog boxes • Bullet items. 

□ Animation control. 

□ Rich Text editor. 

□ Image lists and Tree View controls. 

□ Toolbars, Tradcbars and Statusbars. 
Combine ALL Controls For 

Special Effectsl 

Order your copy todayl 

$ 39.95 

plus shipping 

SPC Order Number: 

1.800.628.0903 
SPC Fax Number: 
1.205.664.6984 
ISBN 0-9644301-0-X 

MMB M 

Using the MFC Windows Controls 

Constructon Kit, you wil ouickty master all 
the skills necessary to implement effective 
AND visually appealing dialogs. This quide 
is written by seasoned programmers who 
show you not only how to make the most 
of the existing controls, but also the new 
ones introduced for Windows 9S and 
Windows NT. This book is short on abstrac¬ 
tion and long on practical examples and 
stands as a bridge between the li and 32 
bit worlds. This is one book every serious 
MfC developer needs for their library. 

■4 

W mSm 

~w —9 Tristar Systems, Inc. 
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Add ZIP (and UNZIP too!) to 
your Windows applications! 


fDynaZIP" 30 

f Data Compression Toolkits 


The new ROYALTY-FREE DynaZIP family of 
developer's fools let you add ZIP and 
UNZIP capabilities to your Windows 
applications. No more “shelling" to 
DOS, no more fussing with proprietary 
compression formats. DLLs, VBXs, OCXs 
and a new database interface provide 
full access from many languages. Fast, 
reliable, and easy to use! 16 and 32 
bit versions, supports long filenames. 


Fully Supported, 
w/30-day no-risk guarantee! 
Call today, toll free: (800) 962-2949 


Innei Media. Inc., Hollis NH USA (603) 465-3216, fax (603) 465-7195 
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-0 Design Tool 


WITH CLASS 2.5 Features: 

• Reverse C++. Delphi 

• Generate Code in nearly any language 

• Import/Export C++ Source Code 

• Template driven Code and Report 
generation for State.Class & Obj. Int. Diagrams 

• Scripting interface to generate 
Custom Reports and Custom Code 

• Supports leading OOA/OOD methods 

• 32-Bit - $295 • 16-Bit - $195 


Dow-uK'.id Dcnm: www.niicrogold.com 
\ .‘IllS.()(iS.4' 1-< ) 1.91IX.(>68.4386 

cmail:7l543.l 1~2 a CompuServe com 
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* Dazzle/VB - image manipulation. 

* VBIite - print/comm/array/B-Tree index ..$149 

* ProMath/VB - numerics/statistics. $149 

* FinLib/VB - financial calculations. $149 

* QuickLine/VB - telephony (multi-line) ...$495 

* SpellCheck/VB - spelling & lookup. $49 

* QB/C/dBase -15 more DOS libraries ...$call 

* Custom - C, VB, ASM programming . ..$80/h 


Develop your VB app faster: Get TeraTech 
tools! Call, E-mail or fax us and well mail you a 
free demo disk ASAP. Or for faster service 
download bv FTP or from our BBS. Call now! 

800-447-9120 ext. 1200 

Dept. 1200.100 Park Avenue, Suite 360, Rockville, MD 20850 USA 
Int i: +1-301-424-3903 Fax:(301)762-8185 BBS: (301) 762-8184 

Copyright TeraTech 1995. A1 rights reserved. Trademarks are the property of their holders. 
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Andrew Binstock's book and remarked 
out loud why people do this: 

#ifdef IN_MAIN_M0DULE 
//define Extern 
//else 

//define Extern extern 
//endif 

Extern int x; 

Extern char fname[20]; 


in another file 


//define IN_MAIN_MODULE 
//include “main.h” 


Other people may have already replied 
by this time but here's my reason, and it 
has nothing to do with compilation 
problems: Each global variable is 
declared and defined in only one line in 
the entire source code, making it easier 
to maintain them. If I wanted to change 
the data type X in the previous example, 
I could just change i nt to 1 ong, and I no 
longer have to look for the declaration 
in some other . h file. 

I can easily add, delete, resize, 
rename the global variables and be sure 
there is no conflict in the declaration 
and definition. I saw this technique first 
in Andrew Tanenbaum's source code to 
Minix ( Operating Systems: Desigri and 
Implementation) and adopted it since. 


Regards, and Happy New Year. 

Ajig Alcalde 
ajig@max.ph.net 

I never thought of that. I probably would 
still not do it that way myself, but at least I 
understand now why some people would. 
Thanks for the explanation! —rib 
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will not work from VB in Windows NT 
(and I assume Win95 as well), since you 
cannot call into a 16-bit DLL from a 32- 
bit platform. I sent mail to Jim Mack to 
confirm, and he agrees. His article 
assumes you are calling from within VB, 
so that vbrun300.dll would already be 
loaded. The good news is that 
vb40032.dll, which ships with VB4.0, 
has the same entry point, and works 
well from within NT. 

Andy 

Thanks for the additional info! —rib 


Dear Mr. Burk, 

I have read your article "Bypassing 
Win95 Printer Device Drivers" (WD/, 


February 1996). I think your article was 
very well written and it was extremely 
important for us, as we develop soft¬ 
ware for driving high-res color printers. 
Working efficiently with printers is a 
topic which is strangely ignored by 
many people, although the amount of 
data which is needed for new, high-res 
color printers is increasing all the time. 

Could you please also refer to 
bypassing Win NT printer device dri¬ 
vers as well? We have difficulties even 
in writing data straight to the parallel 
port (using "CreateFile" and then 
read/write causes the printer to start 
printing only when we close the file and 
not when the data starts to arrive), not 
to mention that we cannot find support 
for EPP or bidirectional parallel port. 


Could you please assist ? 

Many thanks in advance, 

Udi Zohar 
Psik Solutions, Israel 

I should have made that code work with 
NT as well, but I just didn't have time. I 
have not tried it, but I bet the following 
changes to the code would let it work under 
NT: 

a) change D0C_INF0_2 to DOCJNFO.l 

b) remove the Info.dwMode = DI_CHAN- 
N E L_W RITE; line 

When I get more time, I will test this out. 
—rib □ 
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